Keboola Projects API
Manage projects, project members, invitations, join requests and per-project settings.
OpenAPI Specification
openapi: 3.0.0
info:
title: AI Service Actions Projects API
version: 1.0.0
contact:
email: devel@keboola.com
license:
name: MIT
url: https://opensource.org/licenses/MIT
description: Manage projects, project members, invitations, join requests and per-project settings.
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
pattern: '[0-9]+'
example: 4088
requestBody:
required: true
content:
application/json:
schema:
required:
- description
properties:
description:
description: Token description.
type: string
example: Test Token
canManageBuckets:
description: Token has full permissions on tabular storage.
type: boolean
example: true
canManageTokens:
description: Deprecated and ignored — used to control token creation permission inside the project.
type: boolean
example: false
canReadAllFileUploads:
description: Token has full permissions to files staging.
type: boolean
example: true
canPurgeTrash:
description: Allows permanently removing deleted configurations.
type: boolean
example: true
expiresIn:
description: Token lifetime in seconds.
type: integer
example: 60
bucketPermissions:
description: Bucket permissions keyed by bucket id (e.g. `read`, `write`).
type: object
example:
in.c-main: read
additionalProperties:
type: string
componentAccess:
description: Grants access for component configurations. Allowed values are valid component IDs from https://components.keboola.com/components.
type: array
items:
type: string
type: object
example:
description: Test Token
canManageBuckets: true
canReadAllFileUploads: true
canPurgeTrash: true
expiresIn: 60
bucketPermissions:
in.c-main: read
responses:
'201':
description: Storage to
# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/keboola/refs/heads/main/openapi/keboola-projects-api-openapi.yml