Skip to content
Ketvia Developers

Web API reference

Overview

The public Web API for Ketvia Kits. Authenticate with Authorization: Bearer kbot_… (bot token) or Bearer kusr_… (user token); the workspace is implied by the token. JSON in and out. Errors are {code, message, correlationId}. Lists take cursor and limit and return nextCursor.

Base URL: https://api.ketvia.com/api/v1. Incoming webhooks use https://hooks.ketvia.com. OpenAPI 1.0.0: download kits-v1.json or kits-v1.yaml.

Auth

Check a token

GEThttps://api.ketvia.com/api/v1/auth/test

Introspects the calling token: installation, workspace, bot or user, and effective scopes.

Operation ID
authTest
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
None (any valid token)
Rate limit
Reads: 100 per minute per installation

Responses

  • 200 OK

    Schema: AuthTestResponse

    object

    • ok true required
    • tokenType string required — one of "bot", "user"
    • workspaceId string (uuid) required
    • installationId string (uuid) required
    • kitSlug string required — pattern ^[a-z][a-z0-9-]{1,39}$
    • botId string (uuid) | null required
    • userId string (uuid) | null required
    • scopes array of string required
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Rotate a bot token

POSThttps://api.ketvia.com/api/v1/auth/rotate

Issues a new bot token. The calling token keeps working for 24 hours, then expires. A token can be rotated once.

Operation ID
authRotate
Tokens
Bot token (kbot_…)
Required scope
None (any valid token)
Rate limit
Writes: 50 per minute per installation

Responses

  • 200 OK

    Schema: RotateResponse

    object

    • token string required — pattern ^kbot_[A-Za-z0-9_-]{43}$
    • previousTokenExpiresAt string (date-time) required
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 409 Conflict (for example an Idempotency-Key reused with different content). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Exchange an authorization code or refresh token

POSThttps://api.ketvia.com/api/v1/oauth/kit.access

Called by the Kit backend with its client credentials. An authorization code from the install redirect becomes a bot token (or a user token plus refresh token, with PKCE). Refresh tokens are single-use; reusing one revokes the whole grant.

Operation ID
kitAccess
Tokens
Client credentials in the request body (no bearer token)
Required scope
None
Rate limit
No per-installation bucket

Request body

application/json

Schema: KitAccessRequest

one of

  • grantType: "authorization_code" object
    • grantType "authorization_code" required
    • clientId string (uuid) required
    • clientSecret string required — pattern ^kcs_[A-Za-z0-9_-]{43}$
    • code string required — pattern ^kcode_[A-Za-z0-9_-]{43}$
    • redirectUri string required — 1–2000 characters
    • codeVerifier string — pattern ^[A-Za-z0-9._~-]{43,128}$
  • grantType: "refresh_token" object
    • grantType "refresh_token" required
    • clientId string (uuid) required
    • clientSecret string required — pattern ^kcs_[A-Za-z0-9_-]{43}$
    • refreshToken string required — pattern ^kref_[A-Za-z0-9_-]{43}$

Responses

  • 200 OK

    Schema: KitAccessResponse

    one of

    • tokenType: "bot" object
      • tokenType "bot" required
      • accessToken string required — pattern ^kbot_[A-Za-z0-9_-]{43}$
      • botId string (uuid) required
      • installationId string (uuid) required
      • workspace object required
        • id string (uuid) required
        • name string required
      • scopes array of string required
    • tokenType: "user" object
      • tokenType "user" required
      • accessToken string required — pattern ^kusr_[A-Za-z0-9_-]{43}$
      • refreshToken string required — pattern ^kref_[A-Za-z0-9_-]{43}$
      • expiresIn integer required — greater than 0; at most 9007199254740991
      • userId string (uuid) required
      • installationId string (uuid) required
      • workspace object required
        • id string (uuid) required
        • name string required
      • scopes array of string required
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Conversations

List conversations

GEThttps://api.ketvia.com/api/v1/conversations

Bot tokens: the channels the Kit bot was added to. User tokens: the conversations the member belongs to.

Operation ID
conversationsList
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
conversations:read
Rate limit
Reads: 100 per minute per installation

Parameters

NameInSchemaDescription
cursorquery

string — 1–512 characters

limitquery

integer — 1–200; default 50

Responses

  • 200 OK

    Schema: ConversationListResponse

    object

    • conversations array of Conversation required
      • id string (uuid) required
      • kind string required — one of "channel", "dm", "group"
      • visibility string required — one of "public", "private"
      • name string | null required
      • topic string | null required
      • archived boolean required
      • createdAt string (date-time) required
    • nextCursor string | null required — Pass as cursor to fetch the next page; null on the last page.
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Get a conversation

GEThttps://api.ketvia.com/api/v1/conversations/{id}

Operation ID
conversationsGet
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
conversations:read
Rate limit
Reads: 100 per minute per installation

Parameters

NameInSchemaDescription
id requiredpath

string (uuid)

Responses

  • 200 OK

    Schema: ConversationResponse

    object

    • conversation Conversation required
      • id string (uuid) required
      • kind string required — one of "channel", "dm", "group"
      • visibility string required — one of "public", "private"
      • name string | null required
      • topic string | null required
      • archived boolean required
      • createdAt string (date-time) required
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 404 Not found, or not visible to this token (never distinguished). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

List conversation members

GEThttps://api.ketvia.com/api/v1/conversations/{id}/members

Operation ID
conversationsMembers
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
conversations:read
Rate limit
Reads: 100 per minute per installation

Parameters

NameInSchemaDescription
id requiredpath

string (uuid)

cursorquery

string — 1–512 characters

limitquery

integer — 1–200; default 50

Responses

  • 200 OK

    Schema: MemberListResponse

    object

    • members array of object required
      • userId string (uuid) required
      • joinedAt string (date-time) required
    • nextCursor string | null required — Pass as cursor to fetch the next page; null on the last page.
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 404 Not found, or not visible to this token (never distinguished). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Messages

Read message history

GEThttps://api.ketvia.com/api/v1/conversations/{id}/messages

Top-level messages and replies, newest first. Private assistant results are never included.

Operation ID
conversationsHistory
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
messages:read
Rate limit
Reads: 100 per minute per installation

Parameters

NameInSchemaDescription
id requiredpath

string (uuid)

cursorquery

string — 1–512 characters

limitquery

integer — 1–200; default 50

Responses

  • 200 OK

    Schema: MessageListResponse

    object

    • messages array of Message required
      • id string (uuid) required
      • conversationId string (uuid) required
      • author object required
        • kind string required — one of "user", "bot"
        • id string (uuid) required
      • text string | null required
      • blocks array of Block | null required — at most 50 items
      • threadParentId string (uuid) | null required
      • createdAt string (date-time) required
      • editedAt string (date-time) | null required
      • deletedAt string (date-time) | null required
    • nextCursor string | null required — Pass as cursor to fetch the next page; null on the last page.
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 404 Not found, or not visible to this token (never distinguished). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Get a message

GEThttps://api.ketvia.com/api/v1/messages/{id}

Operation ID
messagesGet
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
messages:read
Rate limit
Reads: 100 per minute per installation

Parameters

NameInSchemaDescription
id requiredpath

string (uuid)

Responses

  • 200 OK

    Schema: MessageResponse

    object

    • message Message required
      • id string (uuid) required
      • conversationId string (uuid) required
      • author object required
        • kind string required — one of "user", "bot"
        • id string (uuid) required
      • text string | null required
      • blocks array of Block | null required — at most 50 items
      • threadParentId string (uuid) | null required
      • createdAt string (date-time) required
      • editedAt string (date-time) | null required
      • deletedAt string (date-time) | null required
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 404 Not found, or not visible to this token (never distinguished). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Edit an own message

PATCHhttps://api.ketvia.com/api/v1/messages/{id}

Operation ID
messagesUpdate
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
messages:write
Rate limit
Writes: 50 per minute per installation

Parameters

NameInSchemaDescription
id requiredpath

string (uuid)

Request body

application/json

Schema: UpdateMessageRequest

object

  • text string required — at most 8000 characters; Plain text with optional <@user:ID> mentions. Required: it is the notification and search fallback for blocks.
  • blocks array of BlockInput | null — at most 50 items

Responses

  • 200 OK

    Schema: MessageResponse

    object

    • message Message required
      • id string (uuid) required
      • conversationId string (uuid) required
      • author object required
        • kind string required — one of "user", "bot"
        • id string (uuid) required
      • text string | null required
      • blocks array of Block | null required — at most 50 items
      • threadParentId string (uuid) | null required
      • createdAt string (date-time) required
      • editedAt string (date-time) | null required
      • deletedAt string (date-time) | null required
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 404 Not found, or not visible to this token (never distinguished). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Delete an own message

DELETEhttps://api.ketvia.com/api/v1/messages/{id}

Deleting is idempotent: deleting a deleted message returns the tombstone.

Operation ID
messagesDelete
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
messages:write
Rate limit
Writes: 50 per minute per installation

Parameters

NameInSchemaDescription
id requiredpath

string (uuid)

Responses

  • 200 OK

    Schema: MessageResponse

    object

    • message Message required
      • id string (uuid) required
      • conversationId string (uuid) required
      • author object required
        • kind string required — one of "user", "bot"
        • id string (uuid) required
      • text string | null required
      • blocks array of Block | null required — at most 50 items
      • threadParentId string (uuid) | null required
      • createdAt string (date-time) required
      • editedAt string (date-time) | null required
      • deletedAt string (date-time) | null required
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 404 Not found, or not visible to this token (never distinguished). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

List thread replies

GEThttps://api.ketvia.com/api/v1/messages/{id}/replies

Replies to a top-level message, newest first.

Operation ID
messagesReplies
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
messages:read
Rate limit
Reads: 100 per minute per installation

Parameters

NameInSchemaDescription
id requiredpath

string (uuid)

cursorquery

string — 1–512 characters

limitquery

integer — 1–200; default 50

Responses

  • 200 OK

    Schema: MessageListResponse

    object

    • messages array of Message required
      • id string (uuid) required
      • conversationId string (uuid) required
      • author object required
        • kind string required — one of "user", "bot"
        • id string (uuid) required
      • text string | null required
      • blocks array of Block | null required — at most 50 items
      • threadParentId string (uuid) | null required
      • createdAt string (date-time) required
      • editedAt string (date-time) | null required
      • deletedAt string (date-time) | null required
    • nextCursor string | null required — Pass as cursor to fetch the next page; null on the last page.
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 404 Not found, or not visible to this token (never distinguished). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Post a message

POSThttps://api.ketvia.com/api/v1/messages

Bot tokens post as the Kit bot into channels it was added to; user tokens post as the member. With an Idempotency-Key a retry returns the stored message (200) instead of posting twice; the same key with different content is a 409. Limited to 1 message per second per conversation (burst 5).

Operation ID
messagesPost
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
messages:write
Rate limit
Writes: 50 per minute per installation, plus 1 message per second per conversation (burst 5)

Parameters

NameInSchemaDescription
Idempotency-Keyheader

string — 1–255 characters; pattern ^[\x21-\x7e]+$

Makes a retry safe for 24 hours: the same key returns the stored result; the same key with different content is a 409.

Request body

application/json

Schema: PostMessageRequest

object

  • conversationId string (uuid) required
  • text string required — at most 8000 characters; Plain text with optional <@user:ID> mentions. Required: it is the notification and search fallback for blocks.
  • blocks array of BlockInput — at most 50 items
  • threadParentId string (uuid)

Responses

  • 200 OK

    Schema: MessageResponse

    object

    • message Message required
      • id string (uuid) required
      • conversationId string (uuid) required
      • author object required
        • kind string required — one of "user", "bot"
        • id string (uuid) required
      • text string | null required
      • blocks array of Block | null required — at most 50 items
      • threadParentId string (uuid) | null required
      • createdAt string (date-time) required
      • editedAt string (date-time) | null required
      • deletedAt string (date-time) | null required
  • 201 Created

    Schema: MessageResponse

    object

    • message Message required
      • id string (uuid) required
      • conversationId string (uuid) required
      • author object required
        • kind string required — one of "user", "bot"
        • id string (uuid) required
      • text string | null required
      • blocks array of Block | null required — at most 50 items
      • threadParentId string (uuid) | null required
      • createdAt string (date-time) required
      • editedAt string (date-time) | null required
      • deletedAt string (date-time) | null required
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 404 Not found, or not visible to this token (never distinguished). (Error)
  • 409 Conflict (for example an Idempotency-Key reused with different content). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Reactions

Add a reaction

POSThttps://api.ketvia.com/api/v1/reactions

User tokens only in v1 (Kit bots cannot react yet). Idempotent.

Operation ID
reactionsAdd
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
reactions:write
Rate limit
Writes: 50 per minute per installation

Request body

application/json

Schema: ReactionRequest

object

  • messageId string (uuid) required
  • reaction string required — one of "thumbs_up", "heart", "laugh", "celebrate", "eyes", "thinking", "thanks", "check"

Responses

  • 200 OK

    Schema: OkResponse

    object

    • ok true required
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 404 Not found, or not visible to this token (never distinguished). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Remove a reaction

DELETEhttps://api.ketvia.com/api/v1/reactions

User tokens only in v1. Idempotent.

Operation ID
reactionsRemove
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
reactions:write
Rate limit
Writes: 50 per minute per installation

Parameters

NameInSchemaDescription
messageId requiredquery

string (uuid)

reaction requiredquery

string — one of "thumbs_up", "heart", "laugh", "celebrate", "eyes", "thinking", "thanks", "check"

Responses

  • 200 OK

    Schema: OkResponse

    object

    • ok true required
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 404 Not found, or not visible to this token (never distinguished). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Files

Upload a file

POSThttps://api.ketvia.com/api/v1/files

JSON with base64 content (size and type limits of the files module). User tokens only in v1 (Kit bots cannot upload yet).

Operation ID
filesUpload
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
files:write
Rate limit
Files: 20 per minute per installation

Request body

application/json

Schema: UploadFileRequest

object

  • conversationId string (uuid) required
  • name string required — 1–120 characters
  • mimeType string required — one of "text/plain", "text/markdown", "application/json", "application/pdf", "image/png", "image/jpeg"
  • contentBase64 string required — 4–7000000 characters; pattern ^[A-Za-z0-9+/]+={0,2}$

Responses

  • 201 Created

    Schema: FileResponse

    object

    • file File required
      • id string (uuid) required
      • conversationId string (uuid) required
      • name string required
      • mimeType string required
      • sizeBytes integer required — greater than 0; at most 9007199254740991
      • uploadedByUserId string (uuid) required
      • createdAt string (date-time) required
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 404 Not found, or not visible to this token (never distinguished). (Error)
  • 413 Payload too large. (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Get file metadata

GEThttps://api.ketvia.com/api/v1/files/{id}

Operation ID
filesGet
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
files:read
Rate limit
Reads: 100 per minute per installation

Parameters

NameInSchemaDescription
id requiredpath

string (uuid)

Responses

  • 200 OK

    Schema: FileResponse

    object

    • file File required
      • id string (uuid) required
      • conversationId string (uuid) required
      • name string required
      • mimeType string required
      • sizeBytes integer required — greater than 0; at most 9007199254740991
      • uploadedByUserId string (uuid) required
      • createdAt string (date-time) required
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 404 Not found, or not visible to this token (never distinguished). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Download file content

GEThttps://api.ketvia.com/api/v1/files/{id}/content

The raw bytes with the stored content type.

Operation ID
filesContent
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
files:read
Rate limit
Files: 20 per minute per installation

Parameters

NameInSchemaDescription
id requiredpath

string (uuid)

Responses

  • 200 The file content (Content-Type: application/octet-stream; the stored type is in X-Ketvia-Content-Type).

    string

  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 404 Not found, or not visible to this token (never distinguished). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Users

List workspace members

GEThttps://api.ketvia.com/api/v1/users

Active members. Email addresses only with users:read.email.

Operation ID
usersList
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
users:read
Rate limit
Reads: 100 per minute per installation

Parameters

NameInSchemaDescription
cursorquery

string — 1–512 characters

limitquery

integer — 1–200; default 50

Responses

  • 200 OK

    Schema: UserListResponse

    object

    • users array of User required
      • id string (uuid) required
      • displayName string required
      • role string required — one of "owner", "admin", "member", "guest"
      • email string
    • nextCursor string | null required — Pass as cursor to fetch the next page; null on the last page.
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Who am I

GEThttps://api.ketvia.com/api/v1/users/me

Operation ID
usersMe
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
None (any valid token)
Rate limit
Reads: 100 per minute per installation

Responses

  • 200 OK

    Schema: MeResponse

    object

    • user User | null required
      • id string (uuid) required
      • displayName string required
      • role string required — one of "owner", "admin", "member", "guest"
      • email string
    • bot object | null required
      • id string (uuid) required
      • displayName string required
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Get a member

GEThttps://api.ketvia.com/api/v1/users/{id}

Operation ID
usersGet
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
users:read
Rate limit
Reads: 100 per minute per installation

Parameters

NameInSchemaDescription
id requiredpath

string (uuid)

Responses

  • 200 OK

    Schema: UserResponse

    object

    • user User required
      • id string (uuid) required
      • displayName string required
      • role string required — one of "owner", "admin", "member", "guest"
      • email string
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 404 Not found, or not visible to this token (never distinguished). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Runs

Get an assistant run

GEThttps://api.ketvia.com/api/v1/runs/{id}

User tokens only. Private runs are visible to their requester only.

Operation ID
runsGet
Tokens
User token (kusr_…)
Required scope
runs:read
Rate limit
Reads: 100 per minute per installation

Parameters

NameInSchemaDescription
id requiredpath

string (uuid)

Responses

  • 200 OK

    Schema: RunResponse

    object

    • run Run required
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 403 The token lacks the scope (missing_scope, header X-Ketvia-Required-Scope) or its type cannot call this method (forbidden). (Error)
  • 404 Not found, or not visible to this token (never distinguished). (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Installation

Describe this installation

GEThttps://api.ketvia.com/api/v1/installation

The Kit version, workspace, Kit bot, effective scopes and channels.

Operation ID
installationGet
Tokens
Bot token (kbot_…) or User token (kusr_…)
Required scope
None (any valid token)
Rate limit
Reads: 100 per minute per installation

Responses

  • 200 OK

    Schema: InstallationResponse

    object

    • installation Installation required
      • id string (uuid) required
      • kit object required
        • slug string required — pattern ^[a-z][a-z0-9-]{1,39}$
        • version string required — pattern ^(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,4})\.(0|[1-9]\d{0,5})$
        • displayName string required
      • workspace object required
        • id string (uuid) required
        • name string required
      • botId string (uuid) | null required
      • scopes object required
        • bot array of string required
        • user array of string required
      • channelIds array of string (uuid) required
      • modelDataPolicy "none" required
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Incoming webhooks

Post through an incoming webhook

POSThttps://hooks.ketvia.com/v1/{installationId}/{webhookId}/{secret}

The webhook URL is the credential: keep it secret. Posts as the Kit bot into the webhook's channel; the body cannot choose the channel, author or icon, and interactive elements are removed. Unknown, revoked and uninstalled webhooks all answer 404. 1 request per second per webhook (burst 5), at most 64 KB.

Operation ID
incomingWebhook
Tokens
None: the webhook URL is the credential
Required scope
None
Rate limit
1 request per second per webhook (burst 5)

Parameters

NameInSchemaDescription
installationId requiredpath

string

webhookId requiredpath

string

secret requiredpath

string

Request body

application/json

Schema: IncomingWebhookRequest

object

  • text string required — 1–4000 characters
  • blocks array of BlockInput — at most 50 items

Responses

  • 200 Posted

    Schema: OkResponse

    object

    • ok true required
  • 400 Invalid request (field paths only; submitted values are never echoed). (Error)
  • 401 Missing, invalid, expired or revoked credential. (Error)
  • 404 Not found, or not visible to this token (never distinguished). (Error)
  • 410 Disabled (the channel was archived or the Kit bot was removed). (Error)
  • 413 Payload too large. (Error)
  • 429 Rate limited; retry after Retry-After seconds. (Error)
  • 500 Internal error; quote the correlationId. (Error)

Schemas

Every named schema of the document. Request bodies use the input variants (for exampleBlockInput, where defaults may be omitted); responses use the output variants.

Error

object

  • code string required — one of "validation_error", "unauthenticated", "invalid_credentials", "csrf_rejected", "forbidden", "not_found", "conflict", "idempotency_conflict", "send_context_changed", "workspace_context_changed", "email_taken", "name_taken", "slug_taken", "workspace_login_unavailable", "invalid_invitation", "rate_limited", "payload_too_large", "unsupported_media_type", "internal_error", "invalid_token", "missing_scope", "gone"
  • message string required
  • correlationId string required

Block

one of

  • type: "header" object
    • type "header" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • text string required — 1–150 characters
  • type: "section" object
    • type "section" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • text object required
      • type string required — one of "plain", "mrkdwn"
      • text string required — 1–3000 characters
    • accessory one of
      • type: "button" object
        • type "button" required
        • actionId string required — pattern ^[A-Za-z0-9_.-]{1,64}$
        • text string required — 1–75 characters
        • value string — at most 2000 characters
        • style string required — one of "default", "primary", "danger"; default "default"
        • url string — 1–2000 characters
        • confirm object
          • title string required — 1–100 characters
          • text string required — 1–300 characters
          • confirm string required — 1–30 characters
          • deny string required — 1–30 characters
      • type: "static_select" object
        • type "static_select" required
        • actionId string required — pattern ^[A-Za-z0-9_.-]{1,64}$
        • placeholder string required — 1–150 characters
        • options array of object required — 1–100 items
          • text string required — 1–75 characters
          • value string required — 1–150 characters
      • type: "image" object
        • type "image" required
        • fileId string (uuid) required
        • alt string required — 1–200 characters
  • type: "fields" object
    • type "fields" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • fields array of object required — 1–10 items
      • label string required — 1–60 characters
      • value string required — 1–200 characters
  • type: "metrics" object
    • type "metrics" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • items array of object required — 1–4 items
      • key string required — pattern ^[A-Za-z][A-Za-z0-9_]{0,39}$
      • label string required — 1–60 characters
      • value number required
      • format string — one of "integer", "decimal", "currency", "percent"
      • currency string — pattern ^[A-Z]{3}$
      • primary boolean required
  • type: "table" object
    • type "table" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • columns array of object required — 1–6 items
      • key string required — pattern ^[A-Za-z][A-Za-z0-9_]{0,39}$
      • label string required — 1–60 characters
      • align string required — one of "left", "center", "right"; default "left"
    • rows array of map of string to string required — at most 20 items
  • type: "list" object
    • type "list" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • items array of object required — 1–20 items
      • title string required — 1–150 characters
      • subtitle string — 1–300 characters
      • url string — 1–2000 characters
  • type: "context" object
    • type "context" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • elements array of object required — 1–10 items
      • type string required — one of "plain", "mrkdwn"
      • text string required — 1–3000 characters
  • type: "divider" object
    • type "divider" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
  • type: "image" object
    • type "image" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • fileId string (uuid) required
    • alt string required — 1–200 characters
  • type: "actions" object
    • type "actions" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • elements array of one of required — 1–5 items
      • type: "button" object
        • type "button" required
        • actionId string required — pattern ^[A-Za-z0-9_.-]{1,64}$
        • text string required — 1–75 characters
        • value string — at most 2000 characters
        • style string required — one of "default", "primary", "danger"; default "default"
        • url string — 1–2000 characters
        • confirm object
          • title string required — 1–100 characters
          • text string required — 1–300 characters
          • confirm string required — 1–30 characters
          • deny string required — 1–30 characters
      • type: "static_select" object
        • type "static_select" required
        • actionId string required — pattern ^[A-Za-z0-9_.-]{1,64}$
        • placeholder string required — 1–150 characters
        • options array of object required — 1–100 items
          • text string required — 1–75 characters
          • value string required — 1–150 characters
      • type: "overflow" object
        • type "overflow" required
        • actionId string required — pattern ^[A-Za-z0-9_.-]{1,64}$
        • options array of object required — 1–5 items
          • text string required — 1–75 characters
          • value string required — 1–150 characters

Message

object

  • id string (uuid) required
  • conversationId string (uuid) required
  • author object required
    • kind string required — one of "user", "bot"
    • id string (uuid) required
  • text string | null required
  • blocks array of Block | null required — at most 50 items
  • threadParentId string (uuid) | null required
  • createdAt string (date-time) required
  • editedAt string (date-time) | null required
  • deletedAt string (date-time) | null required

Conversation

object

  • id string (uuid) required
  • kind string required — one of "channel", "dm", "group"
  • visibility string required — one of "public", "private"
  • name string | null required
  • topic string | null required
  • archived boolean required
  • createdAt string (date-time) required

User

object

  • id string (uuid) required
  • displayName string required
  • role string required — one of "owner", "admin", "member", "guest"
  • email string

File

object

  • id string (uuid) required
  • conversationId string (uuid) required
  • name string required
  • mimeType string required
  • sizeBytes integer required — greater than 0; at most 9007199254740991
  • uploadedByUserId string (uuid) required
  • createdAt string (date-time) required

Installation

object

  • id string (uuid) required
  • kit object required
    • slug string required — pattern ^[a-z][a-z0-9-]{1,39}$
    • version string required — pattern ^(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,4})\.(0|[1-9]\d{0,5})$
    • displayName string required
  • workspace object required
    • id string (uuid) required
    • name string required
  • botId string (uuid) | null required
  • scopes object required
    • bot array of string required
    • user array of string required
  • channelIds array of string (uuid) required
  • modelDataPolicy "none" required

Run

object

  • id string (uuid) required
  • botId string (uuid) required
  • conversationId string (uuid) required
  • requesterUserId string (uuid) required
  • audience string required — one of "channel", "private"
  • state string required — one of "received", "queued", "connecting", "awaiting_approval", "succeeded", "failed", "cancelled", "expired", "reconciliation_required"
  • question string required — at most 8000 characters
  • createdAt string (date-time) required
  • updatedAt string (date-time) required
  • finishedAt string (date-time) | null required
  • durationMs integer | null required — 0–9007199254740991
  • steps array of object required
    • state string required — one of "received", "queued", "connecting", "awaiting_approval", "succeeded", "failed", "cancelled", "expired", "reconciliation_required"
    • at string (date-time) required
  • errorCode string | null required
  • attempts integer required — 0–9007199254740991
  • card one of | null required
    • Variant 1 object
      • id string (uuid) required
      • runId string (uuid) required
      • botId string (uuid) required
      • audience string required — one of "channel", "private"
      • requesterUserId string (uuid) required
      • title string required — 1–80 characters
      • headline string required — 1–200 characters
      • source object required
        • label string required — 1–60 characters
        • synthetic boolean required
        • kitSlug string — 1–40 characters
        • official boolean
      • localDate string (date) required
      • timezone string required — 1–64 characters
      • fetchedAt string (date-time) required
      • stale object | null required
        • cachedAt string (date-time) required
      • revoked boolean required
      • createdAt string (date-time) required
      • body array of Block — at most 50 items
      • kind "ok" required
      • metrics array of object required — 1–4 items
        • key string required — 1–40 characters
        • label string required — 1–60 characters
        • value integer required — 0–9007199254740991
        • primary boolean required
      • definition string required — 1–300 characters
    • Variant 2 object
      • id string (uuid) required
      • runId string (uuid) required
      • botId string (uuid) required
      • audience string required — one of "channel", "private"
      • requesterUserId string (uuid) required
      • title string required — 1–80 characters
      • headline string required — 1–200 characters
      • source object required
        • label string required — 1–60 characters
        • synthetic boolean required
        • kitSlug string — 1–40 characters
        • official boolean
      • localDate string (date) required
      • timezone string required — 1–64 characters
      • fetchedAt string (date-time) required
      • stale object | null required
        • cachedAt string (date-time) required
      • revoked boolean required
      • createdAt string (date-time) required
      • body array of Block — at most 50 items
      • kind "zero" required
      • metrics array of object required — 1–4 items
        • key string required — 1–40 characters
        • label string required — 1–60 characters
        • value integer required — 0–9007199254740991
        • primary boolean required
      • definition string required — 1–300 characters
    • Variant 3 object
      • id string (uuid) required
      • runId string (uuid) required
      • botId string (uuid) required
      • audience string required — one of "channel", "private"
      • requesterUserId string (uuid) required
      • title string required — 1–80 characters
      • headline string required — 1–200 characters
      • source object required
        • label string required — 1–60 characters
        • synthetic boolean required
        • kitSlug string — 1–40 characters
        • official boolean
      • localDate string (date) required
      • timezone string required — 1–64 characters
      • fetchedAt string (date-time) required
      • stale object | null required
        • cachedAt string (date-time) required
      • revoked boolean required
      • createdAt string (date-time) required
      • body array of Block — at most 50 items
      • kind "no-data" required
      • metricLabels array of string required — 1–4 items
      • definition string required — 1–300 characters
    • Variant 4 object
      • id string (uuid) required
      • runId string (uuid) required
      • botId string (uuid) required
      • audience string required — one of "channel", "private"
      • requesterUserId string (uuid) required
      • title string required — 1–80 characters
      • headline string required — 1–200 characters
      • source object required
        • label string required — 1–60 characters
        • synthetic boolean required
        • kitSlug string — 1–40 characters
        • official boolean
      • localDate string (date) required
      • timezone string required — 1–64 characters
      • fetchedAt string (date-time) required
      • stale object | null required
        • cachedAt string (date-time) required
      • revoked boolean required
      • createdAt string (date-time) required
      • body array of Block — at most 50 items
      • kind "unavailable" required
      • errorCode string required — 1–64 characters
      • attempts integer required — greater than 0; at most 9007199254740991
      • failedAt string (date-time) required
    • Variant 5 object
      • id string (uuid) required
      • runId string (uuid) required
      • botId string (uuid) required
      • audience string required — one of "channel", "private"
      • requesterUserId string (uuid) required
      • title string required — 1–80 characters
      • headline string required — 1–200 characters
      • source object required
        • label string required — 1–60 characters
        • synthetic boolean required
        • kitSlug string — 1–40 characters
        • official boolean
      • localDate string (date) required
      • timezone string required — 1–64 characters
      • fetchedAt string (date-time) required
      • stale object | null required
        • cachedAt string (date-time) required
      • revoked boolean required
      • createdAt string (date-time) required
      • body array of Block — at most 50 items
      • kind "forbidden" required
  • sharePolicy string — one of "private_only", "channel_allowed"
  • modelText string | null — at most 2000 characters
  • correlationId string — 1–64 characters
  • toolCalls array of object — at most 12 items
    • tool string required — 1–80 characters
    • displayName string — 1–80 characters
    • connectionName string required — 1–60 characters
    • synthetic boolean required
    • grantVersion integer required — greater than 0; at most 9007199254740991
    • startedAt string (date-time) required
    • durationMs integer | null required — 0–9007199254740991
    • state string required — one of "running", "succeeded", "failed"
    • errorCode string | null required — at most 64 characters

AuthTestResponse

object

  • ok true required
  • tokenType string required — one of "bot", "user"
  • workspaceId string (uuid) required
  • installationId string (uuid) required
  • kitSlug string required — pattern ^[a-z][a-z0-9-]{1,39}$
  • botId string (uuid) | null required
  • userId string (uuid) | null required
  • scopes array of string required

RotateResponse

object

  • token string required — pattern ^kbot_[A-Za-z0-9_-]{43}$
  • previousTokenExpiresAt string (date-time) required

KitAccessResponse

one of

  • tokenType: "bot" object
    • tokenType "bot" required
    • accessToken string required — pattern ^kbot_[A-Za-z0-9_-]{43}$
    • botId string (uuid) required
    • installationId string (uuid) required
    • workspace object required
      • id string (uuid) required
      • name string required
    • scopes array of string required
  • tokenType: "user" object
    • tokenType "user" required
    • accessToken string required — pattern ^kusr_[A-Za-z0-9_-]{43}$
    • refreshToken string required — pattern ^kref_[A-Za-z0-9_-]{43}$
    • expiresIn integer required — greater than 0; at most 9007199254740991
    • userId string (uuid) required
    • installationId string (uuid) required
    • workspace object required
      • id string (uuid) required
      • name string required
    • scopes array of string required

ConversationListResponse

object

  • conversations array of Conversation required
  • nextCursor string | null required — Pass as cursor to fetch the next page; null on the last page.

ConversationResponse

object

MemberListResponse

object

  • members array of object required
    • userId string (uuid) required
    • joinedAt string (date-time) required
  • nextCursor string | null required — Pass as cursor to fetch the next page; null on the last page.

MessageListResponse

object

  • messages array of Message required
  • nextCursor string | null required — Pass as cursor to fetch the next page; null on the last page.

MessageResponse

object

OkResponse

object

  • ok true required

FileResponse

object

UserListResponse

object

  • users array of User required
  • nextCursor string | null required — Pass as cursor to fetch the next page; null on the last page.

UserResponse

object

MeResponse

object

  • user User | null required
  • bot object | null required
    • id string (uuid) required
    • displayName string required

RunResponse

object

  • run Run required

InstallationResponse

object

BlockInput

one of

  • type: "header" object
    • type "header" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • text string required — 1–150 characters
  • type: "section" object
    • type "section" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • text object required
      • type string required — one of "plain", "mrkdwn"
      • text string required — 1–3000 characters
    • accessory one of
      • type: "button" object
        • type "button" required
        • actionId string required — pattern ^[A-Za-z0-9_.-]{1,64}$
        • text string required — 1–75 characters
        • value string — at most 2000 characters
        • style string — one of "default", "primary", "danger"; default "default"
        • url string — 1–2000 characters
        • confirm object
          • title string required — 1–100 characters
          • text string required — 1–300 characters
          • confirm string required — 1–30 characters
          • deny string required — 1–30 characters
      • type: "static_select" object
        • type "static_select" required
        • actionId string required — pattern ^[A-Za-z0-9_.-]{1,64}$
        • placeholder string required — 1–150 characters
        • options array of object required — 1–100 items
          • text string required — 1–75 characters
          • value string required — 1–150 characters
      • type: "image" object
        • type "image" required
        • fileId string (uuid) required
        • alt string required — 1–200 characters
  • type: "fields" object
    • type "fields" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • fields array of object required — 1–10 items
      • label string required — 1–60 characters
      • value string required — 1–200 characters
  • type: "metrics" object
    • type "metrics" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • items array of object required — 1–4 items
      • key string required — pattern ^[A-Za-z][A-Za-z0-9_]{0,39}$
      • label string required — 1–60 characters
      • value number required
      • format string — one of "integer", "decimal", "currency", "percent"
      • currency string — pattern ^[A-Z]{3}$
      • primary boolean required
  • type: "table" object
    • type "table" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • columns array of object required — 1–6 items
      • key string required — pattern ^[A-Za-z][A-Za-z0-9_]{0,39}$
      • label string required — 1–60 characters
      • align string — one of "left", "center", "right"; default "left"
    • rows array of map of string to string required — at most 20 items
  • type: "list" object
    • type "list" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • items array of object required — 1–20 items
      • title string required — 1–150 characters
      • subtitle string — 1–300 characters
      • url string — 1–2000 characters
  • type: "context" object
    • type "context" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • elements array of object required — 1–10 items
      • type string required — one of "plain", "mrkdwn"
      • text string required — 1–3000 characters
  • type: "divider" object
    • type "divider" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
  • type: "image" object
    • type "image" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • fileId string (uuid) required
    • alt string required — 1–200 characters
  • type: "actions" object
    • type "actions" required
    • blockId string — pattern ^[A-Za-z0-9_.-]{1,64}$
    • elements array of one of required — 1–5 items
      • type: "button" object
        • type "button" required
        • actionId string required — pattern ^[A-Za-z0-9_.-]{1,64}$
        • text string required — 1–75 characters
        • value string — at most 2000 characters
        • style string — one of "default", "primary", "danger"; default "default"
        • url string — 1–2000 characters
        • confirm object
          • title string required — 1–100 characters
          • text string required — 1–300 characters
          • confirm string required — 1–30 characters
          • deny string required — 1–30 characters
      • type: "static_select" object
        • type "static_select" required
        • actionId string required — pattern ^[A-Za-z0-9_.-]{1,64}$
        • placeholder string required — 1–150 characters
        • options array of object required — 1–100 items
          • text string required — 1–75 characters
          • value string required — 1–150 characters
      • type: "overflow" object
        • type "overflow" required
        • actionId string required — pattern ^[A-Za-z0-9_.-]{1,64}$
        • options array of object required — 1–5 items
          • text string required — 1–75 characters
          • value string required — 1–150 characters

PostMessageRequest

object

  • conversationId string (uuid) required
  • text string required — at most 8000 characters; Plain text with optional <@user:ID> mentions. Required: it is the notification and search fallback for blocks.
  • blocks array of BlockInput — at most 50 items
  • threadParentId string (uuid)

UpdateMessageRequest

object

  • text string required — at most 8000 characters; Plain text with optional <@user:ID> mentions. Required: it is the notification and search fallback for blocks.
  • blocks array of BlockInput | null — at most 50 items

ReactionRequest

object

  • messageId string (uuid) required
  • reaction string required — one of "thumbs_up", "heart", "laugh", "celebrate", "eyes", "thinking", "thanks", "check"

UploadFileRequest

object

  • conversationId string (uuid) required
  • name string required — 1–120 characters
  • mimeType string required — one of "text/plain", "text/markdown", "application/json", "application/pdf", "image/png", "image/jpeg"
  • contentBase64 string required — 4–7000000 characters; pattern ^[A-Za-z0-9+/]+={0,2}$

KitAccessRequest

one of

  • grantType: "authorization_code" object
    • grantType "authorization_code" required
    • clientId string (uuid) required
    • clientSecret string required — pattern ^kcs_[A-Za-z0-9_-]{43}$
    • code string required — pattern ^kcode_[A-Za-z0-9_-]{43}$
    • redirectUri string required — 1–2000 characters
    • codeVerifier string — pattern ^[A-Za-z0-9._~-]{43,128}$
  • grantType: "refresh_token" object
    • grantType "refresh_token" required
    • clientId string (uuid) required
    • clientSecret string required — pattern ^kcs_[A-Za-z0-9_-]{43}$
    • refreshToken string required — pattern ^kref_[A-Za-z0-9_-]{43}$

IncomingWebhookRequest

object

  • text string required — 1–4000 characters
  • blocks array of BlockInput — at most 50 items