Keboola Maintainers API
Manage maintainer records, their members and invitations.
OpenAPI Specification
openapi: 3.0.0
info:
title: AI Service Actions Maintainers API
version: 1.0.0
contact:
email: devel@keboola.com
license:
name: MIT
url: https://opensource.org/licenses/MIT
description: Manage maintainer records, their members and invitations.
tags:
- name: Maintainers
description: Manage maintainer records, their members and invitations.
paths:
/manage/maintainers/{id}/join-maintainer:
post:
tags:
- Maintainers
summary: Join maintainer
description: Joins the specified maintainer as an administrator.
operationId: post_/manage/maintainers/{id}/join-maintainer::JoinMaintainerAction
parameters:
- name: id
in: path
description: Identifier of the maintainer.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 1
responses:
'204':
description: Successfully joined the maintainer.
'400':
description: Returned when the user is already a member of this maintainer.
'404':
description: Returned when the maintainer does not exist.
/manage/maintainers/{id}/users:
get:
tags:
- Maintainers
summary: List maintainer users
description: Returns all users of the specified maintainer.
operationId: get_/manage/maintainers/{id}/users::MaintainerListAdministratorsAction
parameters:
- name: id
in: path
description: Maintainer ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 1
responses:
'200':
description: List of maintainer users.
content:
application/json:
schema:
type: array
items:
properties:
id:
type: integer
example: 23423
name:
type: string
example: Martin Halamicek
email:
type: string
example: martin@keboola.com
type: object
example:
- id: 23423
name: Martin Halamicek
email: martin@keboola.com
'401':
description: Returned when the Manage token is missing or invalid.
'403':
description: Returned when the token does not have access to the maintainer.
'404':
description: Returned when the maintainer does not exist.
post:
tags:
- Maintainers
summary: Add a User to maintainer
description: Either `id` or `email` of a user must be set. If the email is not associated with a user, a new account is created and an invitation is sent.
operationId: post_/manage/maintainers/{id}/users::MaintainerAddAdministratorAction
parameters:
- name: id
in: path
description: Maintainer ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 1
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddMaintainerAdministratorRequest'
responses:
'200':
description: Administrator added successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
'400':
description: Returned when provided parameters are invalid.
'401':
description: Returned when the Manage token is missing or invalid.
'403':
description: Returned when the token does not have access to the maintainer.
'404':
description: Returned when the maintainer does not exist.
/manage/maintainers:
get:
tags:
- Maintainers
summary: List maintainers
description: Returns all maintainers accessible by the manage token.
operationId: get_/manage/maintainers::MaintainerListAction
responses:
'200':
description: List of maintainers.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/MaintainerResponse'
'401':
description: Returned when the Manage token is missing or invalid.
post:
tags:
- Maintainers
summary: Create a maintainer
description: Creates a new maintainer. The user associated with the token will become an admin of the maintainer.
operationId: post_/manage/maintainers::MaintainerCreateAction
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMaintainerRequest'
responses:
'200':
description: Maintainer created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/MaintainerResponse'
'400':
description: Returned when 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 maintainers.
/manage/maintainers/{id}/invitations:
get:
tags:
- Maintainers
summary: List maintainers invitations
description: Returns all pending invitations for the specified maintainer.
operationId: get_/manage/maintainers/{id}/invitations::MaintainerListInvitationsAction
parameters:
- name: id
in: path
description: Maintainer ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 1
responses:
'200':
description: List of invitations.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/MaintainerInvitationDetailResponse'
example:
- id: 112
created: 2018-07-10T10:45:11+0200
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
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 access to the maintainer.
'404':
description: Returned when the maintainer does not exist.
post:
tags:
- Maintainers
summary: Invite a user to a maintainer
description: Only members of the maintainer and superadmins can invite other users.
operationId: post_/manage/maintainers/{id}/invitations::MaintainerCreateInvitationAction
parameters:
- name: id
in: path
description: Maintainer ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 1
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMaintainerInvitationRequest'
responses:
'201':
description: Invitation created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/MaintainerInvitationDetailResponse'
'400':
description: Returned when the email is missing or the user is already a member or already invited.
'401':
description: Returned when the Manage token is missing or invalid.
'403':
description: Returned when the token does not have access to the maintainer.
'404':
description: Returned when the maintainer does not exist.
'422':
description: Returned when the provided email address is not a valid email.
/manage/maintainers/{id}:
get:
tags:
- Maintainers
summary: Retrieve a maintainer
description: Returns detail of the specified maintainer.
operationId: get_/manage/maintainers/{id}::MaintainerDetailAction
parameters:
- name: id
in: path
description: Maintainer ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 1
responses:
'200':
description: Maintainer detail.
content:
application/json:
schema:
$ref: '#/components/schemas/MaintainerDetailResponse'
'401':
description: Returned when the Manage token is missing or invalid.
'403':
description: Returned when the token does not have access to the maintainer.
'404':
description: Returned when the maintainer does not exist.
delete:
tags:
- Maintainers
summary: Delete a maintainer
description: Deletes the specified maintainer.
operationId: delete_/manage/maintainers/{id}::MaintainerDeleteAction
parameters:
- name: id
in: path
description: Maintainer ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 1
responses:
'204':
description: Maintainer deleted successfully.
'400':
description: Returned when the maintainer still has organizations and cannot be deleted.
'401':
description: Returned when the Manage token is missing or invalid.
'403':
description: Returned when the token does not have permission to delete the maintainer.
'404':
description: Returned when the maintainer does not exist.
patch:
tags:
- Maintainers
summary: Update a maintainer
description: A partial update of a maintainer.
operationId: patch_/manage/maintainers/{id}::MaintainerUpdateAction
parameters:
- name: id
in: path
description: Maintainer ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 1
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMaintainerRequest'
responses:
'200':
description: Maintainer updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/MaintainerResponse'
'400':
description: Returned when 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 update this maintainer.
'404':
description: Returned when the maintainer does not exist.
/manage/maintainers/{id}/invitations/{invitationId}:
get:
tags:
- Maintainers
summary: Maintainer invitation detail
description: Returns detail of the specified maintainer invitation.
operationId: get_/manage/maintainers/{id}/invitations/{invitationId}::MaintainerGetInvitationAction
parameters:
- name: id
in: path
description: Maintainer ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 1
- name: invitationId
in: path
description: Invitation ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 113
responses:
'200':
description: Invitation detail.
content:
application/json:
schema:
$ref: '#/components/schemas/MaintainerInvitationDetailResponse'
'401':
description: Returned when the Manage token is missing or invalid.
'403':
description: Returned when the token does not have access to the maintainer.
'404':
description: Returned when the invitation does not exist.
delete:
tags:
- Maintainers
summary: Cancel maintainer invitation
description: Cancels a pending invitation to join the specified maintainer.
operationId: delete_/manage/maintainers/{id}/invitations/{invitationId}::MaintainerDeleteInvitationAction
parameters:
- name: id
in: path
description: Maintainer ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 1
- name: invitationId
in: path
description: Invitation ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 113
responses:
'204':
description: Invitation deleted successfully.
'401':
description: Returned when the Manage token is missing or invalid.
'403':
description: Returned when the token does not have access to the maintainer.
'404':
description: Returned when the invitation does not exist.
/manage/maintainers/{id}/metadata/{metadataId}:
delete:
tags:
- Maintainers
summary: Remove maintainer metadata
description: Only maintainer members and super admins can delete metadata.
operationId: delete_/manage/maintainers/{id}/metadata/{metadataId}::MaintainerDeleteMetadataAction
parameters:
- name: id
in: path
description: Maintainer ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 1
- name: metadataId
in: path
description: Metadata ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 123
responses:
'204':
description: Metadata deleted successfully.
'401':
description: Returned when the Manage token is missing or invalid.
'403':
description: Returned when the token does not have permission to delete this metadata.
'404':
description: Returned when the metadata entry does not exist.
/manage/maintainers/{id}/metadata:
get:
tags:
- Maintainers
summary: List maintainer metadata
description: Only members of the maintainer and super admins can list metadata.
operationId: get_/manage/maintainers/{id}/metadata::MaintainerListMetadataAction
parameters:
- name: id
in: path
description: Maintainer ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 1
responses:
'200':
description: List of metadata.
content:
application/json:
schema:
type: array
items:
properties:
id:
type: integer
example: 123
provider:
type: string
example: user
timestamp:
type: string
example: 2021-02-17T15:05:21+0100
key:
type: string
example: KBC.SomeEnity.metadataKey
value:
type: string
example: Some value
type: object
example:
- id: 123
provider: user
timestamp: 2021-02-17T15:05:21+0100
key: KBC.SomeEnity.metadataKey
value: Some value
- id: 124
provider: user
timestamp: 2021-02-17T15:05:21+0100
key: someMetadataKey
value: Some value
'401':
description: Returned when the Manage token is missing or invalid.
'403':
description: Returned when the token does not have permission to list metadata.
'404':
description: Returned when the maintainer does not exist.
post:
tags:
- Maintainers
summary: Set maintainer metadata
description: 'Sets multiple metadata with one call. If the given key and provider combination already exist
for the maintainer, the data will be updated with the new value and timestamp.
Only maintainer members and super admins can change metadata.'
operationId: post_/manage/maintainers/{id}/metadata::MaintainerSetMetadataAction
parameters:
- name: id
in: path
description: Maintainer ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 1
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SetMaintainerMetadataRequest'
responses:
'201':
description: Metadata set successfully.
content:
application/json:
schema:
type: array
items:
properties:
id:
type: integer
example: 123
provider:
type: string
example: user
timestamp:
type: string
example: 2021-02-17T15:05:21+0100
key:
type: string
example: KBC.SomeEnity.metadataKey
value:
type: string
example: Some value
type: object
example:
- id: 123
provider: user
timestamp: 2021-02-17T15:05:21+0100
key: KBC.SomeEnity.metadataKey
value: Some value
- id: 124
provider: user
timestamp: 2021-02-17T15:05:21+0100
key: someMetadataKey
value: Some value
'400':
description: Returned when the provided metadata is invalid.
'401':
description: Returned when the Manage token is missing or invalid.
'403':
description: Returned when the token does not have permission to set metadata.
'404':
description: Returned when the maintainer does not exist.
/manage/maintainers/{id}/users/{adminId}:
delete:
tags:
- Maintainers
summary: Remove a user from maintainer
description: Removes a user from the specified maintainer.
operationId: delete_/manage/maintainers/{id}/users/{adminId}::MaintainerRemoveAdministratorAction
parameters:
- name: id
in: path
description: Maintainer ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 1
- name: adminId
in: path
description: User ID.
required: true
schema:
type: integer
pattern: '[0-9]+'
example: 1
responses:
'204':
description: Administrator removed successfully.
'400':
description: Returned when the administrator cannot be removed (e.g., last member).
'401':
description: Returned when the Manage token is missing or invalid.
'403':
description: Returned when the token does not have access to the maintainer.
'404':
description: Returned when the maintainer or administrator does not exist.
components:
schemas:
MaintainerDetailResponse:
type: object
allOf:
- $ref: '#/components/schemas/MaintainerResponse'
CreateMaintainerInvitationRequest:
required:
- email
properties:
email:
description: Email of an invited user.
type: string
format: email
example: martin@keboola.com
type: object
example:
email: martin@keboola.com
UserResponse:
required:
- id
- name
- email
- mfaEnabled
- features
- canAccessLogs
- isSuperAdmin
properties:
id:
description: User identifier.
type: integer
example: 2
name:
description: User full name.
type: string
example: Martin
email:
description: User email address.
type: string
example: martin@keboola.com
mfaEnabled:
description: Whether MFA is enabled for the user.
type: boolean
example: true
features:
description: List of assigned features.
type: array
items:
type: string
example:
- inline-manual
canAccessLogs:
description: Whether the user can access logs.
type: boolean
example: true
isSuperAdmin:
description: Whether the user has super admin privileges.
type: boolean
example: true
type: object
example:
id: 2
name: Martin
email: martin@keboola.com
mfaEnabled: true
features:
- inline-manual
canAccessLogs: true
isSuperAdmin: true
CreateMaintainerRequest:
required:
- name
properties:
name:
description: Maintainer name.
type: string
example: Example
defaultConnectionMysqlId:
description: Default MySQL connection ID.
type: integer
example: 324
nullable: true
defaultConnectionSnowflakeId:
description: Default Snowflake connection ID.
type: integer
example: 324
nullable: true
defaultConnectionSynapseId:
description: Default Synapse connection ID.
type: integer
example: 324
nullable: true
defaultConnectionExasolId:
description: Default Exasol connection ID.
type: integer
example: 324
nullable: true
defaultConnectionBigqueryId:
description: Default BigQuery connection ID.
type: integer
example: 324
nullable: true
defaultConnectionTeradataId:
description: Default Teradata connection ID.
type: integer
example: 324
nullable: true
zendeskUrl:
description: Zendesk URL.
type: string
example: https://keboola.zendesk.com
nullable: true
defaultFileStorageId:
description: Default file storage ID.
type: integer
example: 456
nullable: true
type: object
example:
name: Example
defaultConnectionSnowflakeId: 324
zendeskUrl: https://keboola.zendesk.com
SetMaintainerMetadataRequest:
required:
- provider
- metadata
properties:
provider:
description: Metadata provider. Only super admin can change `system` metadata.
type: string
example: user
enum:
- user
- system
metadata:
description: Array of metadata objects.
type: array
items:
required:
- key
- value
properties:
key:
description: Metadata key.
type: string
example: KBC.SomeEnity.metadataKey
value:
description: Metadata value.
type: string
example: Some value
type: object
type: object
example:
provider: user
metadata:
- key: KBC.SomeEnity.metadataKey
value: Some value
- key: someMetadataKey
value: Some value
AddMaintainerAdministratorRequest:
properties:
id:
description: User ID.
type: integer
example: 7234
nullable: true
email:
description: User email.
type: string
format: email
example: martin@keboola.com
nullable: true
type: object
example:
email: martin@keboola.com
MaintainerResponse:
required:
- id
- name
- created
- organizations
properties:
id:
description: Maintainer identifier.
type: integer
example: 123
name:
description: Maintainer name.
type: string
example: Keboola CZ
created:
description: Maintainer creation timestamp.
type: string
format: date-time
example: '2014-11-11T08:40:51.620Z'
defaultConnectionMysqlId:
description: Default MySQL connection identifier.
type: integer
example: 234
nullable: true
defaultConnectionSnowflakeId:
description: Default Snowflake connection identifier.
type: integer
example: 242
nullable: true
defaultConnectionSynapseId:
description: Default Synapse connection identifier.
type: integer
example: 235
nullable: true
defaultConnectionExasolId:
description: Default Exasol connection identifier.
type: integer
example: 236
nullable: true
defaultConnectionBigqueryId:
description: Default BigQuery connection identifier.
type: integer
example: 236
nullable: true
defaultConnectionTeradataId:
description: Default Teradata connection identifier.
type: integer
example: 236
nullable: true
defaultFileStorageId:
description: Default file storage identifier.
type: integer
example: null
nullable: true
zendeskUrl:
description: Zendesk URL for this maintainer.
type: string
example: https://keboola.zendesk.com
nullable: true
organizations:
description: List of organizations belonging to this maintainer.
type: array
items:
properties:
id:
description: Organization identifier.
type: integer
example: 12
name:
description: Organization name.
type: string
example: My Awesome Organization
type: object
type: object
example:
id: 123
name: Keboola CZ
created: '2014-11-11T08:40:51.620Z'
defaultConnectionMysqlId: 234
defaultConnectionSnowflakeId: 242
defaultConnectionSynapseId: 235
defaultConnectionExasolId: 236
defaultConnectionTeradataId: 236
defaultConnectionBigqueryId: 236
defaultFileStorageId: null
zendeskUrl: https://keboola.zendesk.com
organizations:
- id: 12
name: My Awesome Organization
MaintainerInvitationDetailResponse:
required:
- id
- user
- creator
properties:
id:
description: Invitation identifier.
type: integer
example: 113
created:
description: Invitation creation timestamp (ISO 8601 with `+HHMM` offset).
type: string
example: 2018-07-10T10:50:00+0200
nullable: true
user:
description: Invited user.
properties:
id:
type: integer
example: 125
name:
type: string
example: test user 3
email:
type: string
example: spam@keboola.com
type: object
creator:
description: User who created the invitation.
properties:
id:
type: integer
example: 123
name:
type: string
example: test user
email:
type: string
example: martin@keboola.com
type: object
type: object
example:
id: 113
created: 2018-07-10T10:50:00+0200
user:
id: 125
name: test user 3
email: spam@keboola.com
creator:
id: 123
name: test user
email: martin@keboola.com
UpdateMaintainerRequest:
properties:
name:
description: Maintainer name.
type: string
example: Example
nullable: true
defaultConnectionMysqlId:
description: Default MySQL connection ID.
type: integer
example: 324
nullable: true
defaultConnectionSnowflakeId:
description: Default Snowflake connection ID.
type: integer
example: 324
nullable: true
defaultConnectionSynapseId:
description: Default Synapse connection ID.
type: integer
example: 324
nullable: true
defaultConnectionExasolId:
description: Default Exasol connection ID.
type: integer
example: 324
nullable: true
defaultConnectionBigqueryId:
description: Default BigQuery connection ID.
type: integer
example: 324
nullable: true
defaultConnectionTeradataId:
description: Default Teradata connection ID.
type: integer
example: 324
nullable: true
zendeskUrl:
description: Zendesk URL.
type: string
example: https://keboola.zendesk.com
nullable: true
defaultFileStorageId:
description: Default file storage ID.
type: integer
example: 456
nullable: true
type: object
example:
name: Example
defaultConnectionSnowflakeId: 324
zendeskUrl: https://keboola.zendesk.com
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-StorageApi-Token