openapi: 3.0.0 info: title: AI Service Actions Data Apps API version: 1.0.0 contact: email: devel@keboola.com license: name: MIT url: https://opensource.org/licenses/MIT tags: - name: Data Apps paths: /apps: get: summary: List apps operationId: listApps tags: - Data Apps description: 'List project apps. ' security: - storageApiToken: [] parameters: - in: query name: offset required: false schema: type: number minimum: 0 default: 0 - in: query name: limit required: false schema: type: number minimum: 1 maximum: 500 default: 100 - in: query name: componentId required: false description: Filter apps by component ID schema: type: string - in: query name: type required: false description: Filter apps by type (can be specified multiple times) schema: type: array items: type: string enum: - bigquery - python - r - snowflake - streamlit - python-js - in: query name: branchId required: false description: Filter apps by branch ID schema: type: string responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/ExistingApp' '401': description: Unauthorized '403': description: Forbidden post: summary: Create app operationId: createApp tags: - Data Apps description: 'Create new app ' security: - storageApiToken: [] requestBody: description: App data required: true content: application/json: schema: type: object required: - type - branchId - name properties: type: type: string branchId: type: string nullable: true name: type: string description: type: string nullable: true config: type: object nullable: true additionalProperties: true useManagedGitRepo: type: boolean default: false description: 'If `true`, a managed Git repository is provisioned via the Git Service and linked to the app. Repo creation failure aborts app creation (best-effort rollback). The linked repo is deleted when the app is deleted. ' mode: type: string enum: - prod - dev default: prod description: 'Initial run mode for the app. Defaults to `prod`. Can be changed later via PATCH /apps/{appId}. ' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ExistingApp' '401': description: Unauthorized '422': description: Unprocessable Entity /apps/{appId}: get: summary: Get app detail operationId: getApp tags: - Data Apps description: 'Get app detail. ' security: - storageApiToken: [] parameters: - in: path name: appId required: true schema: type: string minLength: 1 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ExistingApp' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found patch: summary: Update app state operationId: patchApp tags: - Data Apps description: 'Update app state. ' security: - manageApiToken: - apps:proxy - storageApiToken: [] parameters: - in: path name: appId required: true schema: type: string minLength: 1 requestBody: description: App state required: true content: application/json: schema: type: object properties: desiredState: type: string enum: - running - stopped lastRequestTimestamp: type: string format: date-time restartIfRunning: type: boolean description: 'If set to `true`, the application will be restarted. Valid only in combination with the `desiredState: "running"`. ' configVersion: type: string minLength: 1 description: 'If set, the app will be updated to the specified configuration version. Valid only in combination with the `desiredState: "running", restartIfRunning: true`. ' updateDependencies: type: boolean description: 'If set to `true`, latest package versions are installed during app startup, instead of using frozen versions. Valid only in combination with the `desiredState: "running", restartIfRunning: true`. ' mode: type: string enum: - prod - dev description: 'Sets the app''s run mode. On a stopped app the mode is updated immediately with no transition. On any non-stopped app the request must also include `desiredState: "running"` and `restartIfRunning: true` so the running pod is restarted in the new mode. If omitted, the app''s current mode is preserved. ' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ExistingApp' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '409': description: 'Conflict — the app is in a terminal state (`deleting`/`deleted`) and cannot be updated, or the requested state transition conflicts with the current state. ' '422': description: Unprocessable Entity delete: summary: Delete app operationId: deleteApp tags: - Data Apps description: 'Delete app ' security: - storageApiToken: [] parameters: - in: path name: appId required: true schema: type: string minLength: 1 responses: '202': description: Accepted '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /apps/{appId}/proxy-config: get: summary: Get proxy config for the app operationId: getAppProxyConfig tags: - Data Apps description: 'Get proxy config for the app ' security: - manageApiToken: - apps:proxy parameters: - in: path name: appId required: true schema: type: string minLength: 1 - in: header name: If-None-Match schema: type: string description: 'Use the last received ETag value to avoid unnecessary responses. If the value matches the current ETag, the server will return 304 Not Modified response with no data and client should use the previous cached response. If client has no previous ETag value, it should omit this header. ' responses: '200': description: OK headers: ETag: description: 'Response content hash. Client should use this value in `If-None-Match` header in following requests to avoid unnecessary responses. ' schema: type: string Cache-Control: description: 'Client should respect this header and cache the response for the specified time to avoid unnecessary requests. ' schema: type: string example: max-age=30 content: application/json: schema: type: object required: - appId - appName - projectId - upstreamAppUrl - authProviders - authRules properties: appId: type: string appName: type: string projectId: type: string upstreamAppUrl: type: string authProviders: type: array items: additionalProperties: type: object required: - id - type additionalProperties: true properties: id: type: string description: 'ID of the provider. Used to reference provider in `authRules`. Each provider ID must be unique. ' type: type: string allowedRoles: type: array items: type: string authRules: type: array items: type: object required: - type - auth additionalProperties: true properties: type: type: string auth: type: array uniqueItems: true items: type: string example: upstreamAppUrl: http://data-app-123.sandbox.svc.cluster.local:8888 authProviders: - id: okta type: oidc allowedRoles: - user clientId: foo '#clientSecret': bar issuerUrl: null authRules: - type: pathPrefix value: / auth: - okta '304': description: 'Not Modified. Returned when `If-None-Match` header is specified and the value matches the current response content hash. If returned, client should use the previous cached response. ' headers: ETag: description: 'Response content hash. Client should use this value in `If-None-Match` header in following requests to avoid unnecessary responses. ' schema: type: string Cache-Control: description: 'Client should respect this header and cache the response for the specified time to avoid unnecessary requests. ' schema: type: string example: max-age=30 '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /apps/{appId}/password: get: summary: Get app password operationId: getAppPassword tags: - Data Apps description: 'Returns app password. Currently applicable only for apps with auth type `password`. ' security: - storageApiToken: [] parameters: - in: path name: appId required: true schema: type: string minLength: 1 responses: '200': description: OK content: application/json: schema: type: object properties: password: type: string '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /apps/{appId}/reset-password: post: summary: Reset app password operationId: resetAppPassword tags: - Data Apps description: 'Reset app password. ' security: - storageApiToken: [] parameters: - in: path name: appId required: true schema: type: string minLength: 1 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ExistingApp' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /apps/{appId}/git-repo: get: summary: Get details of the app's configured Git repository operationId: getAppGitRepo tags: - Data Apps description: 'Returns details of the Git repository configured in the app''s config (`parameters.dataApp.git`). For managed Git repositories both `sshUrl` and `httpsUrl` are returned, fetched from the upstream git-service. For externally configured repositories only the URL matching the configured protocol is returned and the other field is `null`; any embedded credentials are stripped. ' security: - storageApiToken: [] parameters: - in: path name: appId required: true schema: type: string minLength: 1 responses: '200': description: OK content: application/json: schema: type: object required: - sshUrl - httpsUrl - isManagedGitRepo properties: sshUrl: type: string nullable: true description: 'SSH clone URL. `null` for externally configured repositories that use HTTP(S). ' httpsUrl: type: string nullable: true description: 'HTTPS clone URL. `null` for externally configured repositories that use SSH. ' isManagedGitRepo: type: boolean description: 'Whether the repository is a managed Git repository provisioned by the service. ' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '409': description: App has no Git repository configured /apps/{appId}/git-repo/branches: get: summary: List branches of the app's configured Git repository operationId: listAppGitRepoBranches tags: - Data Apps description: 'Returns the remote branches of the Git repository configured in the app''s config (`parameters.dataApp.git`). Works for any configured repository, not only managed Git repositories. ' security: - storageApiToken: [] parameters: - in: path name: appId required: true schema: type: string minLength: 1 responses: '200': description: OK content: application/json: schema: type: array items: type: object required: - branch - comment - sha - author - date properties: branch: type: string comment: type: string sha: type: string author: type: object required: - name - email properties: name: type: string email: type: string date: type: string format: date-time '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '409': description: App has no Git repository configured /apps/{appId}/git-repo/entrypoints: get: summary: List entrypoint files in the app's configured Git repository operationId: listAppGitRepoEntrypoints tags: - Data Apps description: 'Returns the root-level entrypoint files of the Git repository configured in the app''s config (`parameters.dataApp.git`). Uses the configured branch (or the repo''s default branch if none is set). Works for any configured repository, not only managed Git repositories. ' security: - storageApiToken: [] parameters: - in: path name: appId required: true schema: type: string minLength: 1 responses: '200': description: OK content: application/json: schema: type: array items: type: string '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found '409': description: App has no Git repository configured /apps/{appId}/git-repo/credentials: post: summary: Create credential for managed Git repository operationId: createAppGitRepoCredential tags: - Data Apps description: 'Creates a credential (SSH key or HTTP token) for the app''s managed Git repository. For `http_token` credentials, the response includes a one-time `secret` that is not returned on subsequent reads. Requires an admin storage API token. ' security: - storageApiToken: [] parameters: - in: path name: appId required: true schema: type: string minLength: 1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCredentialRequest' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/CreatedCredential' '400': description: Bad Request — invalid payload (wrong type/publicKey combination, missing required fields) '401': description: Unauthorized '403': description: Forbidden — token lacks admin context or CanManageApp fails '404': description: App not found '409': description: App has no managed Git repository get: summary: List credentials for managed Git repository operationId: listAppGitRepoCredentials tags: - Data Apps description: 'Lists non-deleted credentials for the app''s managed Git repository. Requires an admin storage API token. ' security: - storageApiToken: [] parameters: - in: path name: appId required: true schema: type: string minLength: 1 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CredentialList' '401': description: Unauthorized '403': description: Forbidden — token lacks admin context or CanManageApp fails '404': description: App not found /apps/{appId}/git-repo/credentials/{credentialId}: get: summary: Get credential detail operationId: getAppGitRepoCredential tags: - Data Apps description: 'Returns details of a credential registered with the app''s managed Git repository. The response never contains the one-time `secret` field. Requires an admin storage API token. ' security: - storageApiToken: [] parameters: - in: path name: appId required: true schema: type: string minLength: 1 - in: path name: credentialId required: true schema: type: string format: uuid responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Credential' '401': description: Unauthorized '403': description: Forbidden — token lacks admin context or CanManageApp fails '404': description: App or credential not found delete: summary: Revoke and remove a credential operationId: deleteAppGitRepoCredential tags: - Data Apps description: 'Revokes a credential on git-service and soft-deletes the local row. Tolerates git-service 404 as already-removed. Requires an admin storage API token. ' security: - storageApiToken: [] parameters: - in: path name: appId required: true schema: type: string minLength: 1 - in: path name: credentialId required: true schema: type: string format: uuid responses: '204': description: No Content '401': description: Unauthorized '403': description: Forbidden — token lacks admin context or CanManageApp fails '404': description: App or credential not found /apps/{appId}/logs/download: get: summary: Download app logs operationId: downloadAppLogs tags: - Data Apps description: 'Download app logs as a file. ' security: - storageApiToken: [] parameters: - in: path name: appId required: true schema: type: string minLength: 1 responses: '200': description: OK content: text/plain: schema: type: string format: binary '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /apps/{appId}/logs/tail: get: summary: Tail app logs operationId: tailAppLogs tags: - Data Apps description: 'Tail app logs. ' security: - storageApiToken: [] parameters: - in: path name: appId required: true schema: type: string minLength: 1 - in: query name: since schema: type: string example: '2024-11-04T15:30:04.271025817Z' description: 'Only logs newer than the specified timestamp are returned. Timestamp in ISO-8601/RFC-3339 format with nanosecond precision. Cannot be used in combination with `lines`. ' - in: query name: lines schema: type: integer minimum: 1 description: 'Number of lines to return from the end of log. Cannot be used in combination with `since`. ' responses: '200': description: OK content: text/plain: schema: type: string '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /apps/{appId}/runs: get: summary: List app runs operationId: listAppRuns tags: - Data Apps description: 'List app runs for a specific app. ' security: - storageApiToken: [] parameters: - in: path name: appId required: true schema: type: string minLength: 1 - in: query name: offset required: false schema: type: number minimum: 0 default: 0 - in: query name: limit required: false schema: type: number minimum: 1 maximum: 500 default: 100 responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/AppRun' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found /apps/{appId}/runs/{runId}: get: summary: Get app run detail operationId: getAppRun tags: - Data Apps description: 'Get detailed information about a specific app run. ' security: - storageApiToken: [] parameters: - in: path name: appId required: true schema: type: string minLength: 1 - in: path name: runId required: true schema: type: string minLength: 1 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AppRun' '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found components: schemas: CreateCredentialRequest: type: object required: - type - permissions properties: type: type: string enum: - ssh_key - http_token publicKey: type: string description: SSH public key. Required iff `type` is `ssh_key`; forbidden otherwise. name: type: string default: '' description: Optional caller-supplied display label. permissions: type: string enum: - readOnly - readWrite Credential: type: object required: - id - type - name - permissions - ownerAdminId - createdAt properties: id: type: string format: uuid type: type: string enum: - ssh_key - http_token name: type: string permissions: type: string enum: - readOnly - readWrite ownerAdminId: type: string createdAt: type: string format: date-time ExistingApp: type: object required: - id - projectId - componentId - branchId - configId - configVersion - state - desiredState - lastRequestTimestamp - provisioningStrategy - mode properties: id: type: string type: type: string nullable: true description: App type (e.g. streamlit, jupyter, python, python-js) projectId: type: string componentId: type: string branchId: type: string nullable: true configId: type: string configVersion: type: string state: type: string enum: - created - starting - restarting - running - stopping - stopped - deleting - deleted desiredState: type: string enum: - running - stopped - deleted mode: type: string enum: - prod - dev description: 'Current run mode for the app. Can be changed via PATCH /apps/{appId}. ' lastRequestTimestamp: type: string format: date-time nullable: true lastStartTimestamp: type: string format: date-time nullable: true url: type: string nullable: true autoSuspendAfterSeconds: type: integer description: '`0` means whatever default is configured on backend ' autoRestartEnabled: type: boolean description: 'Whether auto-restart is enabled for the app. When disabled, the app can be started only manually by setting `desiredState` to `running`, not by opening the app URL. ' size: type: string nullable: true description: App size (e.g. micro, tiny, small, medium, large, external) provisioningStrategy: type: string enum: - jobQueue - operator hasManagedGitRepo: type: boolean description: 'Whether the app has a managed Git repository provisioned by the service. Apps with a managed repository expose additional endpoints under `/apps/{appId}/git-repo/credentials`. ' CreatedCredential: allOf: - $ref: '#/components/schemas/Credential' - type: object properties: secret: type: string description: One-time secret returned only at creation for `http_token` credentials. AppRun: type: object required: - id - appId - mode properties: id: type: string description: Unique identifier for the app run (UUID in RFC 4122 format) appId: type: string description: ID of the app this run belongs to state: type: string enum: - starting - running - failed - finished nullable: true description: Current state of the app run createdAt: type: string format: date-time nullable: true description: Timestamp when the app run was created (ISO 8601 ATOM format) startedAt: type: string format: date-time nullable: true description: Timestamp when the app run started (ISO 8601 ATOM format) stoppedAt: type: string format: date-time nullable: true description: Timestamp when the app run stopped (ISO 8601 ATOM format) startupLogs: type: string nullable: true description: Startup logs from the app run runtimeSize: type: string nullable: true description: Runtime size used for this app run (e.g., small, medium, large) configVersion: type: string nullable: true description: Configuration version used for this app run failureReason: type: object nullable: true description: User-facing cause of a failed run. Set only when state is "failed". properties: reason: type: string nullable: true description: Short, stable, machine-readable identifier (UI i18n key) message: type: string nullable: true description: Human-readable description of the failure mode: type: string enum: - prod - dev default: prod description: Run mode this app run was started with CredentialList: type: object required: - credentials properties: credentials: type: array items: $ref: '#/components/schemas/Credential' securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-StorageApi-Token