Keboola Projects API

openapi: 3.2.0
info:
  title: Keboola Connection Management Projects API
  description: 'The Keboola Connection Management API covers all tasks required for managing

    projects, plus super-admin features for controlling and monitoring Keboola Connection.


    ## Projects management

    * Create, modify and delete maintainers, organizations and projects

    * Move projects between organizations

    * Define project limits

    * Provision storage backends

    * Access project management activity log


    ## Projects monitoring

    * Monitoring of projects across organizations and maintainers


    ## Super user control and monitoring

    * UI release and deployment

    * Components management

    * Final project delete

    * Workers start/shutdown, etc.


    ## Authentication

    The API authenticates with a personal access token sent in the `X-KBC-ManageApiToken`

    header. Tokens can be created in

    [Account Settings](https://connection.keboola.com/admin/account/change-password)

    in Keboola Connection. A token is tied to an administrator and inherits that

    administrator''s permissions; when the administrator is disabled or deleted, all

    their tokens become invalid.


    ```

    curl -H "X-KBC-ManageApiToken: USER_TOKEN" https://connection.keboola.com/manage/tokens/verify

    ```


    ## Token types

    | Type  | Tied to a user | Token string visible only on create | Description |

    | ----- | -------------- | ----------------------------------- | ----------- |

    | user  | Yes            | Yes                                 | Full access to maintainers, organizations and projects the user can see. |

    | super | No             | Yes                                 | KBC management. Scopes such as `super_ui_deploy`, `super_monitoring` etc. can be limited per-token. |


    Legacy Apiary reference: see the

    [Manage API blueprint](https://github.com/keboola/connection/blob/master/Package/ManageApiPhpClient/apiary.apib)

    for the historical document this OpenAPI spec is migrating from.

    '
  version: '1.0'
servers:
- url: https://connection.keboola.com
  description: AWS US East
- url: https://connection.eu-central-1.keboola.com
  description: AWS EU Central
- url: https://connection.north-europe.azure.keboola.com
  description: Azure North Europe
- url: https://connection.east-us-2.azure.keboola-testing.com
  description: Azure Testing
security:
- StorageKey: []
- ManageKey: []
- BearerAuth: []
tags:
- name: Projects
  description: Manage projects, project members, invitations, join requests and per-project settings.
paths:
  /manage/organizations/{id}/projects:
    get:
      tags:
      - Projects
      summary: List projects for an organization
      description: Returns all projects belonging to the organization specified by its ID.
      operationId: get_/manage/organizations/{id}/projects::OrganizationListProjectsAction
      parameters:
      - name: id
        in: path
        description: Identifier of the organization.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 5
      responses:
        '200':
          description: List of organization projects.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
              example:
              - id: 101
                name: test project
                type: production
                region: eu-west-1
                created: '2017-02-15T14:25:15+01:00'
                expires: null
                features:
                - featureName
                dataSizeBytes: 49152
                rowsCount: 200
                hasMysql: false
                hasSynapse: false
                hasExasol: false
                hasTeradata: false
                hasSnowflake: true
                defaultBackend: snowflake
                hasTryModeOn: '0'
                limits:
                  limitName:
                    name: limitName
                    value: 10
                metrics: {}
                isDisabled: false
                billedMonthlyPrice: null
                dataRetentionTimeInDays: 1
                fileStorageProvider: aws
                isBYODB: false
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have access to the organization, or when MFA is required.
        '404':
          description: Returned when the organization does not exist.
    post:
      tags:
      - Projects
      summary: Add a project
      description: 'A project will be created from a default template which defines its limits. Only members

        of the organization can create a project.'
      operationId: post_/manage/organizations/{id}/projects::OrganizationCreateProjectAction
      parameters:
      - name: id
        in: path
        description: Identifier of the organization; projects have to be created in an organization.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 5
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - name
              properties:
                name:
                  description: Project name.
                  type: string
                  example: My Demo
                type:
                  description: Project type or template string identifier. One of `production`, `poc`, `demo` (default `production`).
                  type: string
                  example: demo
                  enum:
                  - production
                  - poc
                  - demo
                defaultBackend:
                  description: Project default backend (default `snowflake`).
                  type: string
                  example: snowflake
                dataRetentionTimeInDays:
                  description: Data retention in days for Time Travel.
                  type: integer
                  example: 7
              type: object
            example:
              name: My Demo
              type: demo
              defaultBackend: snowflake
              dataRetentionTimeInDays: 7
      responses:
        '200':
          description: Project created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationCreateProjectResponse'
        '400':
          description: Returned when the provided parameters are invalid.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to create a project in the organization.
        '404':
          description: Returned when the organization does not exist.
  /manage/project-templates/{templateId}:
    get:
      tags:
      - Projects
      summary: Project template detail
      description: Return detail of a specific project template.
      operationId: get_/manage/project-templates/{templateId}::ProjectTemplateDetailAction
      parameters:
      - name: templateId
        in: path
        description: String identifier of the project template.
        required: true
        schema:
          type: string
        example: poc15Days
      responses:
        '200':
          description: Project template detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectTemplateResponse'
        '401':
          description: Returned when the Manage token is missing or invalid.
        '404':
          description: Returned when the project template does not exist.
  /manage/project-templates:
    get:
      tags:
      - Projects
      summary: List templates
      description: Return a list of available project templates.
      operationId: get_/manage/project-templates::ProjectTemplateListAction
      responses:
        '200':
          description: Project templates list.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProjectTemplateResponse'
              example:
              - id: poc15Days
                name: POC 15 days
                description: Proof of concept. 15 days trial.
                expirationDays: 15
                billedMonthlyPrice: null
                hasTryModeOn: false
                defaultBackend: snowflake
              - id: poc15DaysGuideMode
                name: POC Guide Mode
                description: Proof of concept. 15 days trial - Guide Mode.
                expirationDays: 15
                billedMonthlyPrice: null
                hasTryModeOn: true
                defaultBackend: snowflake
        '401':
          description: Returned when the Manage token is missing or invalid.
  /manage/projects/{projectId}/users:
    get:
      tags:
      - Projects
      summary: List project users
      description: Returns a list of users (administrators) for the project specified by its ID.
      operationId: get_/manage/projects/{projectId}/users::ProjectListAdministratorsAction
      parameters:
      - name: projectId
        in: path
        description: Identifier of the project.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 4088
      responses:
        '200':
          description: List of project users.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
              example:
              - id: 123
                name: test user
                email: martin@keboola.com
                features: []
                expires: null
                created: 2016-02-29T08:01:13+0200
                reason: ''
                role: admin
                status: active
                invitor:
                  id: 124
                  name: test user 2
                  email: spam@keboola.com
                approver: null
                canApproveMergeRequests: true
              - id: 124
                name: test user 2
                email: spam@keboola.com
                features: []
                expires: 2016-03-22T15:01:13+0200
                created: 2016-02-22T15:01:13+0200
                reason: temporary test
                role: guest
                status: active
                invitor: null
                approver:
                  id: 1
                  name: admin 1
                  email: dev@keboola.com
                canApproveMergeRequests: false
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to list project users.
        '404':
          description: Returned when the project does not exist.
    post:
      tags:
      - Projects
      summary: Add a user to a project
      description: 'Only members of the project or its organization are allowed to add new users to the project.


        An optional expiration (seconds) and reason for joining can be added to the request.

        Roles `admin`, `guest`, `readOnly` and `share` are allowed (default `admin`).'
      operationId: post_/manage/projects/{projectId}/users::ProjectAddAdministratorAction
      parameters:
      - name: projectId
        in: path
        description: Identifier of the project.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 4088
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - email
              properties:
                email:
                  description: Email of an invited user.
                  type: string
                  format: email
                  example: martin@keboola.com
                role:
                  description: Role assigned in the project (default `admin`).
                  type: string
                  example: admin
                  enum:
                  - admin
                  - guest
                  - readOnly
                  - share
                expirationSeconds:
                  description: After how many seconds the membership of a user will expire.
                  type: integer
                  example: 3600
                reason:
                  description: Reason for adding the user to the project.
                  type: string
                  example: temporary test
              type: object
            example:
              email: martin@keboola.com
              role: admin
              expirationSeconds: 3600
              reason: temporary test
      responses:
        '204':
          description: User added to the project successfully.
        '400':
          description: Returned when the request body is invalid or the user is not activated.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to add project users.
        '404':
          description: Returned when the project does not exist.
        '422':
          description: Returned when the email address is invalid or fails domain validation.
  /manage/projects/{projectId}/join-requests/{joinRequestId}:
    get:
      tags:
      - Projects
      summary: Join request detail
      description: Returns detail of a specific join request for the specified project.
      operationId: get_/manage/projects/{projectId}/join-requests/{joinRequestId}::ProjectGetJoinRequestAction
      parameters:
      - name: projectId
        in: path
        description: Identifier of the project.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 4088
      - name: joinRequestId
        in: path
        description: Identifier of the join request.
        required: true
        schema:
          type: integer
          pattern: '[1-9][0-9]*'
        example: 1235
      responses:
        '200':
          description: Join request detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectJoinRequestDetailResponse'
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to view the join request.
        '404':
          description: Returned when the project or join request does not exist.
    put:
      tags:
      - Projects
      summary: Approve join request
      description: 'Only members of the project can approve join requests.


        The user that submitted the join request will be added to the project.'
      operationId: put_/manage/projects/{projectId}/join-requests/{joinRequestId}::ProjectApproveJoinRequestAction
      parameters:
      - name: projectId
        in: path
        description: Identifier of the project.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 4088
      - name: joinRequestId
        in: path
        description: Identifier of the join request.
        required: true
        schema:
          type: integer
          pattern: '[1-9][0-9]*'
        example: 1235
      responses:
        '202':
          description: Join request approved successfully.
        '400':
          description: Returned when the requesting user is not activated.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to approve the join request.
        '404':
          description: Returned when the project or join request does not exist.
    delete:
      tags:
      - Projects
      summary: Reject join request
      description: Only members of the project can reject join requests.
      operationId: delete_/manage/projects/{projectId}/join-requests/{joinRequestId}::ProjectRejectJoinRequestAction
      parameters:
      - name: projectId
        in: path
        description: Identifier of the project.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 4088
      - name: joinRequestId
        in: path
        description: Identifier of the join request.
        required: true
        schema:
          type: integer
          pattern: '[1-9][0-9]*'
        example: 1235
      responses:
        '204':
          description: Join request rejected successfully.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to reject the join request.
        '404':
          description: Returned when the project or join request does not exist.
  /manage/projects/{projectId}/file-storage:
    post:
      tags:
      - Projects
      summary: Assign project file Storage
      description: This action can be performed only by a super admin. Assigns a file storage to the given project and returns updated project details.
      operationId: post_/manage/projects/{projectId}/file-storage::ProjectAssignFileStorageAction
      parameters:
      - name: projectId
        in: path
        description: Identifier of the project.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 4088
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - fileStorageId
              properties:
                fileStorageId:
                  description: ID of file Storage.
                  type: integer
                  example: 32
              type: object
            example:
              fileStorageId: 32
      responses:
        '200':
          description: Project detail response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          description: Returned when the request body is invalid.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to assign file storage (super admin only).
        '404':
          description: Returned when the project or file storage does not exist.
  /manage/projects/{projectId}/storage-backend:
    post:
      tags:
      - Projects
      summary: Assign project Storage backend
      description: 'This action can be performed only by a super admin.


        One backend connection of each type (Snowflake, BigQuery) can be assigned to a project.

        Connection type is automatically detected from the passed connection identifier.'
      operationId: post_/manage/projects/{projectId}/storage-backend::ProjectAssignStorageBackendAction
      parameters:
      - name: projectId
        in: path
        description: Identifier of the project.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 4088
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignStorageBackendRequest'
            example:
              storageBackendId: 32
      responses:
        '200':
          description: Project detail response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          description: Returned when the storage backend cannot be assigned to the project, the backend is not found, the backend root credentials are not activated, or a Teradata backend assignment is attempted via this endpoint.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to assign the storage backend (super admin only).
        '404':
          description: Returned when the project does not exist.
  /manage/projects/{projectId}/invitations/{invitationId}:
    get:
      tags:
      - Projects
      summary: Project invitation detail
      description: Returns detail of the specified invitation for the project.
      operationId: get_/manage/projects/{projectId}/invitations/{invitationId}::ProjectGetInvitationAction
      parameters:
      - name: projectId
        in: path
        description: Identifier of the project.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 4088
      - name: invitationId
        in: path
        description: Identifier of the invitation.
        required: true
        schema:
          type: integer
          pattern: '[1-9][0-9]*'
        example: 113
      responses:
        '200':
          description: Invitation detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectInvitationDetailResponse'
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to view invitations.
        '404':
          description: Returned when the project or invitation does not exist.
    delete:
      tags:
      - Projects
      summary: Cancel project invitation
      description: Only members of the project or its organization are allowed to cancel project invitation.
      operationId: delete_/manage/projects/{projectId}/invitations/{invitationId}::ProjectCancelInvitationAction
      parameters:
      - name: projectId
        in: path
        description: Identifier of the project.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 4088
      - name: invitationId
        in: path
        description: Identifier of the invitation to cancel.
        required: true
        schema:
          type: integer
          pattern: '[1-9][0-9]*'
        example: 113
      responses:
        '204':
          description: Invitation cancelled successfully.
        '400':
          description: Returned when the invited user is not activated.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to cancel invitations.
        '404':
          description: Returned when the project or invitation does not exist.
  /manage/projects/{projectId}/disabled:
    post:
      tags:
      - Projects
      summary: Change project disabled status
      description: Enables or disables the project specified by its ID.
      operationId: post_/manage/projects/{projectId}/disabled::ProjectChangeDisabledAction
      parameters:
      - name: projectId
        in: path
        description: Identifier of the project.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 4088
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - isDisabled
              properties:
                isDisabled:
                  description: Enable or disable project.
                  type: boolean
                  example: true
                disableReason:
                  description: Why the project is disabled.
                  type: string
                  example: Project maintenance
                estimatedEndTime:
                  description: When the project will be enabled. Accepts an RFC 3339 timestamp or a relative `strtotime`-compatible value such as `+1 hour`.
                  type: string
                  example: +1 hour
              type: object
            example:
              isDisabled: true
              disableReason: Project maintenance
              estimatedEndTime: +1 hour
      responses:
        '200':
          description: Project detail response after status change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          description: Returned when the request body is invalid.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to change the project disabled status.
        '404':
          description: Returned when the project does not exist.
  /manage/projects/{projectId}/organizations:
    post:
      tags:
      - Projects
      summary: Move a project
      description: 'Moves the project to a different organization. If the project was listed as

        `activityCenterProjectId` on its previous organization, that field will be set to `null`.'
      operationId: post_/manage/projects/{projectId}/organizations::ProjectChangeOrganizationAction
      parameters:
      - name: projectId
        in: path
        description: Identifier of the project.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 4088
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - organizationId
              properties:
                organizationId:
                  description: ID of destination organization.
                  type: integer
                  example: 523
              type: object
            example:
              organizationId: 523
      responses:
        '200':
          description: Project detail response after organization change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          description: Returned when the request body is invalid or organizationId is missing.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to change the project organization.
        '404':
          description: Returned when the project or destination organization does not exist.
  /manage/projects/{projectId}/invitations:
    get:
      tags:
      - Projects
      summary: List project invitations
      description: Returns a list of invitations for the project specified by its ID.
      operationId: get_/manage/projects/{projectId}/invitations::ProjectListInvitationsAction
      parameters:
      - name: projectId
        in: path
        description: Identifier of the project.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 4088
      responses:
        '200':
          description: List of project invitations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProjectInvitationDetailResponse'
              example:
              - id: 112
                created: 2018-07-10T10:45:11+0200
                expires: null
                reason: ''
                user:
                  id: 124
                  name: test user 2
                  email: spam@keboola.com
                creator:
                  id: 123
                  name: test user
                  email: martin@keboola.com
              - id: 113
                created: 2018-07-10T10:50:00+0200
                expires: 2018-07-12T10:50:00+0200
                reason: Help with Restbox configuration
                user:
                  id: 125
                  name: test user 3
                  email: spam@keboola.com
                creator:
                  id: 123
                  name: test user
                  email: martin@keboola.com
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to list invitations.
        '404':
          description: Returned when the project does not exist.
    post:
      tags:
      - Projects
      summary: Invite a user to a project
      description: 'Only members of the project or its organization are allowed to invite new users to the project.


        An optional expiration (seconds) and reason for joining can be added to the request.

        Roles `admin`, `guest`, `readOnly` and `share` are allowed (default `admin`).'
      operationId: post_/manage/projects/{projectId}/invitations::ProjectCreateInvitationAction
      parameters:
      - name: projectId
        in: path
        description: Identifier of the project.
        required: true
        schema:
          type: integer
          pattern: '[0-9]+'
        example: 4088
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - email
              properties:
                email:
                  description: Email of an invited user.
                  type: string
                  format: email
                  example: martin@keboola.com
                role:
                  description: Role assigned to the invited user (default `admin`).
                  type: string
                  example: admin
                  enum:
                  - admin
                  - guest
                  - readOnly
                  - share
                expirationSeconds:
                  description: After how many seconds the invitation and membership of a user will expire.
                  type: integer
                  example: 3600
                reason:
                  description: Reason for inviting user.
                  type: string
                  example: Help with component configuration
              type: object
            example:
              email: martin@keboola.com
              role: admin
              expirationSeconds: 3600
              reason: Help with component configuration
      responses:
        '201':
          description: Invitation created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectInvitationDetailResponse'
              example:
                id: 113
                created: 2018-07-10T10:50:00+0200
                expires: 2018-07-10T11:50:00+0200
                reason: Help with component configuration
                role: admin
                user:
                  id: 125
                  name: test user 3
                  email: spam@keboola.com
                creator:
                  id: 123
                  name: test user
                  email: martin@keboola.com
        '400':
          description: Returned when the request body is invalid or the invited user is not activated.
        '401':
          description: Returned when the Manage token is missing or invalid.
        '403':
          description: Returned when the token does not have permission to create invitations.
        '404':
          description: Returned when the project does not exist.
        '422':
          description: Returned when the email address is invalid or fails domain validation.
  /manage/projects/{projectId}/tokens:
    post:
      tags:
      - Projects
      summary: Create Storage token
      description: 'Requires the management token of an admin who is either superuser or has joined the

        project previously. Alternatively it can be called with an application token with

        scope `manage:storage-tokens`.


        The `canManageTokens` attribute is deprecated and will be ignored.'
      operationId: post_/manage/projects/{projectId}/tokens::ProjectCreateStorageTokenAction
      parameters:
      - name: projectId
        in: path
        description: Identifier of the project.
        required: true
        schema:
          type: integer
          patter

# --- truncated at 32 KB (84 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/keboola/refs/heads/main/openapi/keboola-projects-api-openapi.yml