Developer API reference

Overview

The API behind ketvia kits …. Authenticate with Authorization: Bearer kdev_…, a developer token created in the developer portal. The token acts as its member in its own workspace only. Rate limit: 60 requests per minute per token. Errors are {code, message, correlationId}.

Base URL: https://api.ketvia.com/api/v1. OpenAPI 1.0.0: downloadkits-dev-v1.json or kits-dev-v1.yaml.

Note

This page is generated from the same route table the API serves. Authenticate with a developer token (kdev_…) created in the developer portal; it acts as its member in its own workspace only. The Web API and its tokens are described in Web API reference. Errors use the shape on Rate limits and errors.

Developer

Check a developer token

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

The token, its workspace and whether that workspace is a developer sandbox.

Operation ID

devMe

Token

Developer token (kdev_…)

Responses

• 200 OK

  Schema: DevMeResponse

  object

  • workspaceId string (uuid) required
  • userId string (uuid) required
  • sandbox boolean required
  • token object required
    • id string (uuid) required
    • name string required
    • createdAt string (date-time) required
    • expiresAt string (date-time) required
    • lastUsedAt string (date-time) | null required
    • revokedAt 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)
• 429 Rate limited; retry after Retry-After seconds. (Error)
• 500 Internal error; quote the correlationId. (Error)

List the workspace's Kits

GEThttps://api.ketvia.com/api/v1/dev/kits

Operation ID

devKitsList

Token

Developer token (kdev_…)

Responses

• 200 OK

  Schema: KitListResponse

  object

  • kits array of Kit required
    • kitId string (uuid) required
    • slug string required — pattern ^[a-z][a-z0-9-]{1,39}$
    • displayName string required
    • distribution string required — one of "private", "unlisted", "directory"
    • state string required — one of "active", "suspended"
    • createdAt string (date-time) required
    • latestVersion string | null required — pattern ^(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,4})\.(0|[1-9]\d{0,5})$
    • latestPublishedVersion string | null required — pattern ^(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,4})\.(0|[1-9]\d{0,5})$
    • installedHere boolean 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)
• 429 Rate limited; retry after Retry-After seconds. (Error)
• 500 Internal error; quote the correlationId. (Error)

Get a Kit with its versions, domains and credential metadata

GEThttps://api.ketvia.com/api/v1/dev/kits/{kitId}

Operation ID

devKitsGet

Token

Developer token (kdev_…)

Parameters

Name	In	Schema	Description
kitId required	path	string (uuid)

Responses

• 200 OK

  Schema: KitDetailResponse

  object

  • detail object required
    • kit Kit required
      • kitId string (uuid) required
      • slug string required — pattern ^[a-z][a-z0-9-]{1,39}$
      • displayName string required
      • distribution string required — one of "private", "unlisted", "directory"
      • state string required — one of "active", "suspended"
      • createdAt string (date-time) required
      • latestVersion string | null required — pattern ^(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,4})\.(0|[1-9]\d{0,5})$
      • latestPublishedVersion string | null required — pattern ^(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,4})\.(0|[1-9]\d{0,5})$
      • installedHere boolean required
    • versions array of Version required
      • id string (uuid) required
      • version string required — pattern ^(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,4})\.(0|[1-9]\d{0,5})$
      • published boolean required
      • publishedAt string (date-time) | null required
      • createdAt string (date-time) required
      • consentHash string required — pattern ^[a-f0-9]{64}$
      • manifestHash string required — pattern ^[a-f0-9]{64}$
      • distribution string required — one of "private", "unlisted", "directory"
    • domains array of Domain required
      • domain string required — at most 253 characters; pattern ^(?=.{3,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$
      • method string required — one of "dns", "well_known"
      • verified boolean required
      • verifiedAt string (date-time) | null required
      • challenge string required
      • proof object required
        • dns object required
          • type "TXT" required
          • host string required
          • value string required
        • wellKnown object required
          • url string required
          • body object required
            • kitId string (uuid) required
            • token string required
    • credentials object required
      • clientSecret object | null required
        • createdAt string (date-time) required
      • signingSecret object | null required
        • generation integer required — greater than 0; at most 9007199254740991
        • createdAt string (date-time) required
        • previousExpiresAt string (date-time) | null required
    • installLink object required
      • active boolean required
      • createdAt string (date-time) | null required
    • endpointHosts array of string required
    • unverifiedHosts array of string 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)

Validate a manifest

POSThttps://api.ketvia.com/api/v1/dev/kits/validate

Schema, slug ownership, domain coverage and the consent difference to the latest published version. Changes nothing.

Operation ID

devKitsValidate

Token

Developer token (kdev_…)

Request body

application/json

Schema: ValidateRequest

object

• manifest string required — 2–65536 characters

Responses

• 200 OK

  Schema: ValidateResponse

  object

  • valid boolean required
  • problems array of object required
    • path string required — at most 200 characters
    • message string required — at most 300 characters
  • warnings array of object required
    • path string required — at most 200 characters
    • message string required — at most 300 characters
  • consent ConsentSummary | null 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})$
    • official boolean required
    • displayName string required — 1–60 characters
    • description string required — 1–500 characters
    • developerName string required — 1–80 characters
    • privacyPolicyUrl string (uri) required — at most 2000 characters
    • iconUrl string (uri) | null required — at most 2000 characters
    • categories array of string required — at most 5 items
    • sample boolean required
    • externalAuth object | null required
      • displayName string required — 1–80 characters
      • requiredScopes array of string required — at most 10 items
      • optionalScopes array of string required — at most 10 items
    • botScopes array of string required — at most 20 items
    • tools array of object required — at most 50 items
      • name string required — pattern ^[a-z][a-z0-9_]{0,63}$
      • displayName string required — 1–80 characters
      • description string required — 1–1000 characters
      • access string required — one of "read", "write"
      • dataClass string required — one of "aggregate", "standard", "personal", "sensitive"
      • audience string required — one of "any", "private"
    • requestedModelDataPolicy string required — one of "none", "answer"
    • consentHash string required — pattern ^[a-f0-9]{64}$
    • available boolean required
    • installed boolean required
    • ownedByWorkspace boolean
    • userScopes array of string — at most 20 items
  • hosts array of string required
  • unverifiedHosts array of string required
  • diff ConsentDiff | null required
    • addedBotScopes array of string required
    • removedBotScopes array of string required
    • addedUserScopes array of string required
    • removedUserScopes array of string required
    • addedTools array of object required
      • name string required
      • access string required — one of "read", "write"
      • dataClass string required — one of "aggregate", "standard", "personal", "sensitive"
      • audience string required — one of "any", "private"
    • removedTools array of string required
    • changedTools array of object required
      • name string required
      • from object required
        • access string required — one of "read", "write"
        • dataClass string required — one of "aggregate", "standard", "personal", "sensitive"
        • audience string required — one of "any", "private"
      • to object required
        • access string required — one of "read", "write"
        • dataClass string required — one of "aggregate", "standard", "personal", "sensitive"
        • audience string required — one of "any", "private"
      • wider boolean required
    • addedEvents array of string required
    • removedEvents array of string required
    • addedCommands array of string required
    • removedCommands array of string required
    • externalAuth string required — one of "unchanged", "added", "removed", "widened", "narrowed"
    • modelDataPolicy object | null required
      • from string required — one of "none", "answer"
      • to string required — one of "none", "answer"
    • wider boolean required
  • existingKitId string (uuid) | 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)
• 429 Rate limited; retry after Retry-After seconds. (Error)
• 500 Internal error; quote the correlationId. (Error)

Upload a manifest as a new version

POSThttps://api.ketvia.com/api/v1/dev/kits/versions

Creates the Kit on first use (private). The version is a draft unless publish is true; a version is immutable once registered, so uploading the same version with a different manifest is a 409.

Operation ID

devKitsUpload

Token

Developer token (kdev_…)

Request body

application/json

Schema: UploadRequest

object

• manifest string required — 2–65536 characters
• publish boolean — default false

Responses

• 201 Created

  Schema: UploadResponse

  object

  • kitId string (uuid) required
  • created boolean required
  • version Version required
    • id string (uuid) required
    • version string required — pattern ^(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,4})\.(0|[1-9]\d{0,5})$
    • published boolean required
    • publishedAt string (date-time) | null required
    • createdAt string (date-time) required
    • consentHash string required — pattern ^[a-f0-9]{64}$
    • manifestHash string required — pattern ^[a-f0-9]{64}$
    • distribution string required — one of "private", "unlisted", "directory"
  • installationId string (uuid) | 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)
• 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)

Publish a draft version

POSThttps://api.ketvia.com/api/v1/dev/kits/{kitId}/versions/{version}/publish

Makes the version installable and applies the manifest distribution. unlisted needs a verified domain for every endpoint host.

Operation ID

devKitsPublish

Token

Developer token (kdev_…)

Parameters

Name	In	Schema	Description
kitId required	path	string (uuid)
version required	path	string — pattern ^(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,4})\.(0|[1-9]\d{0,5})$

Responses

• 200 OK

  Schema: UploadResponse

  object

  • kitId string (uuid) required
  • created boolean required
  • version Version required
    • id string (uuid) required
    • version string required — pattern ^(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,4})\.(0|[1-9]\d{0,5})$
    • published boolean required
    • publishedAt string (date-time) | null required
    • createdAt string (date-time) required
    • consentHash string required — pattern ^[a-f0-9]{64}$
    • manifestHash string required — pattern ^[a-f0-9]{64}$
    • distribution string required — one of "private", "unlisted", "directory"
  • installationId string (uuid) | 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)

Read the delivery and error log of a Kit

GEThttps://api.ketvia.com/api/v1/dev/kits/{kitId}/logs

Operation ID

devKitsLogs

Token

Developer token (kdev_…)

Parameters

Name	In	Schema	Description
kitId required	path	string (uuid)
cursor	query	string — at most 512 characters
limit	query	integer — 1–100; default 50
source	query	string — one of "tool_call", "audit", "delivery"
level	query	string — one of "info", "error"

Responses

• 200 OK

  Schema: LogResponse

  object

  • entries array of object required
    • id string required — at most 100 characters
    • at string (date-time) required
    • source string required — one of "tool_call", "audit", "delivery"
    • level string required — one of "info", "error"
    • event string required — at most 120 characters
    • installationId string (uuid) | null required
    • status string | null required — at most 40 characters
    • errorCode string | null required — at most 80 characters
    • durationMs integer | null required — 0–9007199254740991
    • httpStatus integer | null required — 100–599
    • attempt integer | null required — greater than 0; at most 9007199254740991
  • nextCursor string | null required
  • sources array of string 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)

Install a manifest into the developer sandbox on a tunnel URL

POSThttps://api.ketvia.com/api/v1/dev/sandbox/dev-install

Only for a token created in the developer sandbox workspace. Moves every endpoint URL onto the origin of url (a third-party tunnel; Ketvia runs no relay), registers the manifest as a private Kit version of the sandbox and installs or updates it there.

Operation ID

devKitsDevInstall

Token

Developer token (kdev_…)

Request body

application/json

Schema: DevInstallRequest

object

• manifest string required — 2–65536 characters
• url string required — 1–2000 characters

Responses

• 201 Created

  Schema: DevInstallResponse

  object

  • kitId string (uuid) 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})$
  • installationId string (uuid) required
  • endpoints array of string required
  • signingSecret object | null required
    • signingSecret string required — pattern ^kss_[A-Za-z0-9_-]{43}$
    • generation integer required — greater than 0; at most 9007199254740991
    • previousExpiresAt 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)
• 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)

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", "kit_unavailable"
• message string required
• correlationId string required

ConsentSummary

object

• 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})$
• official boolean required
• displayName string required — 1–60 characters
• description string required — 1–500 characters
• developerName string required — 1–80 characters
• privacyPolicyUrl string (uri) required — at most 2000 characters
• iconUrl string (uri) | null required — at most 2000 characters
• categories array of string required — at most 5 items
• sample boolean required
• externalAuth object | null required
  • displayName string required — 1–80 characters
  • requiredScopes array of string required — at most 10 items
  • optionalScopes array of string required — at most 10 items
• botScopes array of string required — at most 20 items
• tools array of object required — at most 50 items
  • name string required — pattern ^[a-z][a-z0-9_]{0,63}$
  • displayName string required — 1–80 characters
  • description string required — 1–1000 characters
  • access string required — one of "read", "write"
  • dataClass string required — one of "aggregate", "standard", "personal", "sensitive"
  • audience string required — one of "any", "private"
• requestedModelDataPolicy string required — one of "none", "answer"
• consentHash string required — pattern ^[a-f0-9]{64}$
• available boolean required
• installed boolean required
• ownedByWorkspace boolean
• userScopes array of string — at most 20 items

ConsentDiff

object

• addedBotScopes array of string required
• removedBotScopes array of string required
• addedUserScopes array of string required
• removedUserScopes array of string required
• addedTools array of object required
  • name string required
  • access string required — one of "read", "write"
  • dataClass string required — one of "aggregate", "standard", "personal", "sensitive"
  • audience string required — one of "any", "private"
• removedTools array of string required
• changedTools array of object required
  • name string required
  • from object required
    • access string required — one of "read", "write"
    • dataClass string required — one of "aggregate", "standard", "personal", "sensitive"
    • audience string required — one of "any", "private"
  • to object required
    • access string required — one of "read", "write"
    • dataClass string required — one of "aggregate", "standard", "personal", "sensitive"
    • audience string required — one of "any", "private"
  • wider boolean required
• addedEvents array of string required
• removedEvents array of string required
• addedCommands array of string required
• removedCommands array of string required
• externalAuth string required — one of "unchanged", "added", "removed", "widened", "narrowed"
• modelDataPolicy object | null required
  • from string required — one of "none", "answer"
  • to string required — one of "none", "answer"
• wider boolean required

Version

object

• id string (uuid) required
• version string required — pattern ^(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,4})\.(0|[1-9]\d{0,5})$
• published boolean required
• publishedAt string (date-time) | null required
• createdAt string (date-time) required
• consentHash string required — pattern ^[a-f0-9]{64}$
• manifestHash string required — pattern ^[a-f0-9]{64}$
• distribution string required — one of "private", "unlisted", "directory"

Kit

object

• kitId string (uuid) required
• slug string required — pattern ^[a-z][a-z0-9-]{1,39}$
• displayName string required
• distribution string required — one of "private", "unlisted", "directory"
• state string required — one of "active", "suspended"
• createdAt string (date-time) required
• latestVersion string | null required — pattern ^(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,4})\.(0|[1-9]\d{0,5})$
• latestPublishedVersion string | null required — pattern ^(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,4})\.(0|[1-9]\d{0,5})$
• installedHere boolean required

Domain

object

• domain string required — at most 253 characters; pattern ^(?=.{3,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$
• method string required — one of "dns", "well_known"
• verified boolean required
• verifiedAt string (date-time) | null required
• challenge string required
• proof object required
  • dns object required
    • type "TXT" required
    • host string required
    • value string required
  • wellKnown object required
    • url string required
    • body object required
      • kitId string (uuid) required
      • token string required

DevMeResponse

object

• workspaceId string (uuid) required
• userId string (uuid) required
• sandbox boolean required
• token object required
  • id string (uuid) required
  • name string required
  • createdAt string (date-time) required
  • expiresAt string (date-time) required
  • lastUsedAt string (date-time) | null required
  • revokedAt string (date-time) | null required

KitListResponse

object

• kits array of Kit required

KitDetailResponse

object

• detail object required
  • kit Kit required
  • versions array of Version required
  • domains array of Domain required
  • credentials object required
    • clientSecret object | null required
      • createdAt string (date-time) required
    • signingSecret object | null required
      • generation integer required — greater than 0; at most 9007199254740991
      • createdAt string (date-time) required
      • previousExpiresAt string (date-time) | null required
  • installLink object required
    • active boolean required
    • createdAt string (date-time) | null required
  • endpointHosts array of string required
  • unverifiedHosts array of string required

ValidateResponse

object

• valid boolean required
• problems array of object required
  • path string required — at most 200 characters
  • message string required — at most 300 characters
• warnings array of object required
  • path string required — at most 200 characters
  • message string required — at most 300 characters
• consent ConsentSummary | null required
• hosts array of string required
• unverifiedHosts array of string required
• diff ConsentDiff | null required
• existingKitId string (uuid) | null required

UploadResponse

object

• kitId string (uuid) required
• created boolean required
• version Version required
• installationId string (uuid) | null required

LogResponse

object

• entries array of object required
  • id string required — at most 100 characters
  • at string (date-time) required
  • source string required — one of "tool_call", "audit", "delivery"
  • level string required — one of "info", "error"
  • event string required — at most 120 characters
  • installationId string (uuid) | null required
  • status string | null required — at most 40 characters
  • errorCode string | null required — at most 80 characters
  • durationMs integer | null required — 0–9007199254740991
  • httpStatus integer | null required — 100–599
  • attempt integer | null required — greater than 0; at most 9007199254740991
• nextCursor string | null required
• sources array of string required

DevInstallResponse

object

• kitId string (uuid) 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})$
• installationId string (uuid) required
• endpoints array of string required
• signingSecret object | null required
  • signingSecret string required — pattern ^kss_[A-Za-z0-9_-]{43}$
  • generation integer required — greater than 0; at most 9007199254740991
  • previousExpiresAt string (date-time) | null required

ValidateRequest

object

• manifest string required — 2–65536 characters

UploadRequest

object

• manifest string required — 2–65536 characters
• publish boolean — default false

DevInstallRequest

object

• manifest string required — 2–65536 characters
• url string required — 1–2000 characters