Skip to main content
API docs by Redocly

Kamiwaza REST API (1.0.0)

Download OpenAPI specification:Download

health

Ping

Simple ping endpoint for liveness testing.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
null

Whoami

Return current user information from headers.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
null

auth

Login

Login endpoint - proxies to Keycloak for authentication. Returns Keycloak's RS256 tokens directly.

Request Body schema: application/x-www-form-urlencoded
required
username
required
string (Username)

Account username (Keycloak login)

password
required
string (Password)

Account password

grant_type
string (Grant Type)
Default: "password"

OAuth 2.0 grant type

scope
string (Scope)
Default: "openid email profile offline_access"

Space-separated scopes. Default mirrors the Kamiwaza profile scopes

Client Id (string) or Client Id (null) (Client Id)

Keycloak client ID. Leave blank to use AUTH_GATEWAY_KEYCLOAK_CLIENT_ID (default 'kamiwaza-platform').

Client Secret (string) or Client Secret (null) (Client Secret)

Client secret if the Keycloak client requires one. Leave blank for the default setup.

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "bearer",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "id_token": "string"
}

Refresh Token

Refresh access token using refresh token.

query Parameters
Refresh Token (string) or Refresh Token (null) (Refresh Token)

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "bearer",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "id_token": "string"
}

Get Current User

Return the authenticated user resolved from the bearer token or ForwardAuth headers.

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "username": "string",
  • "email": "string",
  • "groups": [
    ],
  • "roles": [
    ],
  • "sub": "string"
}

Oidc Callback

OIDC callback handler. Exchanges authorization code for tokens, sets auth cookie, and redirects user to Kamiwaza UI.

This endpoint should be configured as a redirect URI in Keycloak.

query Parameters
code
required
string (Code)
State (string) or State (null) (State)
Session State (string) or Session State (null) (Session State)

Responses

Response samples

Content type
application/json
null

Register Idp

Register or update an external IdP in Keycloak.

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
provider
required
string (Provider)

'google' or 'oidc'

GoogleConfig (object) or null
OIDCConfig (object) or null
ensure_redirects
boolean (Ensure Redirects)
Default: true

Responses

Request samples

Content type
application/json
{
  • "provider": "string",
  • "google": {
    },
  • "oidc": {
    },
  • "ensure_redirects": true
}

Response samples

Content type
application/json
null

Update Idp

Authorizations:
OAuth2LoginBearerAuth
path Parameters
alias
required
string (Alias)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
provider
required
string (Provider)

'google' or 'oidc'

GoogleConfig (object) or null
OIDCConfig (object) or null
ensure_redirects
boolean (Ensure Redirects)
Default: true

Responses

Request samples

Content type
application/json
{
  • "provider": "string",
  • "google": {
    },
  • "oidc": {
    },
  • "ensure_redirects": true
}

Response samples

Content type
application/json
null

Toggle Idp

Authorizations:
OAuth2LoginBearerAuth
path Parameters
alias
required
string (Alias)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
enabled
required
boolean (Enabled)

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
null

Delete Idp

Authorizations:
OAuth2LoginBearerAuth
path Parameters
alias
required
string (Alias)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
null

List Idps

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
null

List Idps Public

Public listing of enabled IdPs (no secrets). Useful for login UI. Returns alias, providerId, enabled, displayName.

Responses

Response samples

Content type
application/json
null

List Users

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Resolve User By Identifier

Resolve a user by external_id (Keycloak sub) or local DB id.

Useful for admin UIs that need to display owner information when owner_user_id stores a Keycloak sub rather than a local PK.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
identifier
required
string (Identifier)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "string",
  • "email": "string",
  • "roles": [
    ],
  • "active": true,
  • "deleted": true,
  • "is_external": true,
  • "external_id": "string",
  • "linked_subject_id": "string",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Get User Detail

Authorizations:
OAuth2LoginBearerAuth
path Parameters
user_id
required
string <uuid> (User Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "string",
  • "email": "string",
  • "roles": [
    ],
  • "active": true,
  • "deleted": true,
  • "is_external": true,
  • "external_id": "string",
  • "linked_subject_id": "string",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Update Local

Authorizations:
OAuth2LoginBearerAuth
path Parameters
user_id
required
string <uuid> (User Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Username (string) or Username (null) (Username)
Email (string) or Email (null) (Email)
Active (boolean) or Active (null) (Active)
Array of Roles (strings) or Roles (null) (Roles)

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "email": "string",
  • "active": true,
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "string",
  • "email": "string",
  • "roles": [
    ],
  • "active": true,
  • "deleted": true,
  • "is_external": true,
  • "external_id": "string",
  • "linked_subject_id": "string",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Delete Local

Authorizations:
OAuth2LoginBearerAuth
path Parameters
user_id
required
string <uuid> (User Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "string",
  • "email": "string",
  • "roles": [
    ],
  • "active": true,
  • "deleted": true,
  • "is_external": true,
  • "external_id": "string",
  • "linked_subject_id": "string",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Create Local

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
username
required
string (Username)
Email (string) or Email (null) (Email)
password
required
string (Password)
Array of Roles (strings) or Roles (null) (Roles)

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "email": "string",
  • "password": "string",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "string",
  • "email": "string",
  • "roles": [
    ],
  • "active": true,
  • "deleted": true,
  • "is_external": true,
  • "external_id": "string",
  • "linked_subject_id": "string",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Reset Password

Authorizations:
OAuth2LoginBearerAuth
path Parameters
user_id
required
string <uuid> (User Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
new_password
required
string (New Password)

Responses

Request samples

Content type
application/json
{
  • "new_password": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "string",
  • "email": "string",
  • "roles": [
    ],
  • "active": true,
  • "deleted": true,
  • "is_external": true,
  • "external_id": "string",
  • "linked_subject_id": "string",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Change My Password

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
current_password
required
string (Current Password)
new_password
required
string (New Password)

Responses

Request samples

Content type
application/json
{
  • "current_password": "string",
  • "new_password": "string"
}

Response samples

Content type
application/json
{
  • "changed": true
}

Saml Metadata

Responses

Response samples

Content type
application/json
null

Saml Login

query Parameters
Redirect Uri (string) or Redirect Uri (null) (Redirect Uri)

Relative redirect after login

Responses

Response samples

Content type
application/json
null

Saml Acs

Responses

Response samples

Content type
application/json
null

Saml Sls

Responses

Response samples

Content type
application/json
null

Saml Sls

Responses

Response samples

Content type
application/json
null

Browser Login

Initiate browser-based login by redirecting to Keycloak. Uses the public URL for browser access.

query Parameters
Redirect Uri (string) or Redirect Uri (null) (Redirect Uri)

Where to redirect after login

Redirect (string) or Redirect (null) (Redirect)

Where to redirect after login, used by ForwardAuth

Provider (string) or Provider (null) (Provider)

Identity provider hint (e.g., 'google')

Responses

Response samples

Content type
application/json
null

Cac Login

Entry point for CAC/mTLS authentication.

Responses

Response samples

Content type
application/json
null

Create Runtime Launch Endpoint

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
target_kind
string (Target Kind)
Default: "runtime_app"
Enum: "runtime_app" "runtime_tool"
target_id
required
string (Target Id) [ 1 .. 255 ] characters
requested_workroom_id
required
string (Requested Workroom Id) [ 1 .. 64 ] characters
launch_path
string (Launch Path)
Default: "/"

Responses

Request samples

Content type
application/json
{
  • "target_kind": "runtime_app",
  • "target_id": "string",
  • "requested_workroom_id": "string",
  • "launch_path": "/"
}

Response samples

Content type
application/json
{
  • "launch_code": "string",
  • "launch_url": "string",
  • "expires_in": 0
}

Exchange Runtime Launch Endpoint

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
launch_code
required
string (Launch Code) non-empty

Responses

Request samples

Content type
application/json
{
  • "launch_code": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "refresh_token": "string",
  • "token_type": "bearer",
  • "expires_in": 0,
  • "refresh_expires_in": 0,
  • "workroom_id": "string",
  • "target_kind": "runtime_app",
  • "target_id": "string"
}

Refresh Runtime Launch Endpoint

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "refresh_token": "string",
  • "token_type": "bearer",
  • "expires_in": 0,
  • "refresh_expires_in": 0,
  • "workroom_id": "string",
  • "target_kind": "runtime_app",
  • "target_id": "string"
}

Root

Root endpoint for auth service.

Responses

Response samples

Content type
application/json
null

Health

Health check endpoint.

Responses

Response samples

Content type
application/json
null

Jwks

Publish Kamiwaza public keys (Lite mode or for PAT/SA in Full).

Responses

Response samples

Content type
application/json
null

Get Pat Config

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "scope_hierarchy": [
    ],
  • "scope_labels": {
    },
  • "available_scopes": [
    ],
  • "default_scope": "string",
  • "ttl": {
    }
}

Create Pat

Create a Personal Access Token for the current user. Returns the JWT once.

Authorizations:
OAuth2LoginBearerAuth
query Parameters
Name (string) or Name (null) (Name)
Ttl Seconds (integer) or Ttl Seconds (null) (Ttl Seconds)
Scope (string) or Scope (null) (Scope)
Aud (string) or Aud (null) (Aud)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
Any of
Name (string) or Name (null) (Name)
Ttl Seconds (integer) or Ttl Seconds (null) (Ttl Seconds)

TTL in seconds for the PAT

Scope (string) or Scope (null) (Scope)
Aud (string) or Aud (null) (Aud)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "string",
  • "ttl_seconds": 60,
  • "scope": "string",
  • "aud": "string"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "pat": {
    }
}

List My Pats

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "pats": [
    ]
}

Revoke My Pat

Authorizations:
OAuth2LoginBearerAuth
path Parameters
jti
required
string (Jti)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
null

Mint Dev Token

Mint a development token when dev endpoints are enabled.

query Parameters
user_id
string (User Id)
Default: "dev-user"

Subject for minted token

roles
string (Roles)
Default: "user"

Comma-separated roles to embed

Responses

Response samples

Content type
application/json
null

Logout

Logout endpoint - revokes tokens with Keycloak, prepares front-channel logout, and clears cookies.

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
null

Front Channel Logout

Browser-facing logout redirect that clears Keycloak SSO session.

query Parameters
Redirect Uri (string) or Redirect Uri (null) (Redirect Uri)

Responses

Response samples

Content type
application/json
null

List Relations

Authorizations:
OAuth2LoginBearerAuth
query Parameters
tenant
string (Tenant)
Default: "__default__"

Tenant identifier

Object Namespace (string) or Object Namespace (null) (Object Namespace)

Filter by object namespace

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Diff Relations

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
manifest
required
string (Manifest)
Tenant (string) or Tenant (null) (Tenant)

Responses

Request samples

Content type
application/json
{
  • "manifest": "string",
  • "tenant": "string"
}

Response samples

Content type
application/json
null

Revoke Relations

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
manifest
required
string (Manifest)
Tenant (string) or Tenant (null) (Tenant)
dry_run
boolean (Dry Run)
Default: false

Responses

Request samples

Content type
application/json
{
  • "manifest": "string",
  • "tenant": "string",
  • "dry_run": false
}

Response samples

Content type
application/json
{
  • "tenant": "string",
  • "dry_run": true,
  • "count": 0,
  • "tuples": [
    ]
}

Export Tuple Audit Events

Authorizations:
OAuth2LoginBearerAuth
query Parameters
tenant
string (Tenant)
Default: "__default__"

Tenant identifier

Updated After (string) or Updated After (null) (Updated After)

ISO-8601 timestamp filter (updated_at >= value)

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "tenant": "string",
  • "exported_at": "2019-08-24T14:15:22Z",
  • "count": 0,
  • "events": [
    ]
}

Export Decision Events

Authorizations:
OAuth2LoginBearerAuth
query Parameters
Tenant (string) or Tenant (null) (Tenant)

Filter events to a tenant identifier

Result (string) or Result (null) (Result)

Filter by decision result

Updated After (string) or Updated After (null) (Updated After)

ISO-8601 timestamp filter for decision time

limit
integer (Limit) [ 1 .. 1000 ]
Default: 200

Maximum number of events

Cursor (integer) or Cursor (null) (Cursor)

Resume export from this sequence cursor

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "tenant": "string",
  • "result": "string",
  • "since": "2019-08-24T14:15:22Z",
  • "count": 0,
  • "events": [
    ],
  • "next_cursor": 0,
  • "has_more": true
}

Revoke Session

Authorizations:
OAuth2LoginBearerAuth
path Parameters
session_id
required
string (Session Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Purge Subject Sessions

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
tenant_id
required
string (Tenant Id)
subject_namespace
string (Subject Namespace)
Default: "user"
subject_id
required
string (Subject Id)

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "string",
  • "subject_namespace": "user",
  • "subject_id": "string"
}

Response samples

Content type
application/json
{
  • "revoked": 0
}

auth_gateway

Login

Login endpoint - proxies to Keycloak for authentication. Returns Keycloak's RS256 tokens directly.

Request Body schema: application/x-www-form-urlencoded
required
username
required
string (Username)

Account username (Keycloak login)

password
required
string (Password)

Account password

grant_type
string (Grant Type)
Default: "password"

OAuth 2.0 grant type

scope
string (Scope)
Default: "openid email profile offline_access"

Space-separated scopes. Default mirrors the Kamiwaza profile scopes

Client Id (string) or Client Id (null) (Client Id)

Keycloak client ID. Leave blank to use AUTH_GATEWAY_KEYCLOAK_CLIENT_ID (default 'kamiwaza-platform').

Client Secret (string) or Client Secret (null) (Client Secret)

Client secret if the Keycloak client requires one. Leave blank for the default setup.

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "bearer",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "id_token": "string"
}

Refresh Token

Refresh access token using refresh token.

query Parameters
Refresh Token (string) or Refresh Token (null) (Refresh Token)

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "bearer",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "id_token": "string"
}

Get Current User

Return the authenticated user resolved from the bearer token or ForwardAuth headers.

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "username": "string",
  • "email": "string",
  • "groups": [
    ],
  • "roles": [
    ],
  • "sub": "string"
}

auth-idp

Register Idp

Register or update an external IdP in Keycloak.

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
provider
required
string (Provider)

'google' or 'oidc'

GoogleConfig (object) or null
OIDCConfig (object) or null
ensure_redirects
boolean (Ensure Redirects)
Default: true

Responses

Request samples

Content type
application/json
{
  • "provider": "string",
  • "google": {
    },
  • "oidc": {
    },
  • "ensure_redirects": true
}

Response samples

Content type
application/json
null

Update Idp

Authorizations:
OAuth2LoginBearerAuth
path Parameters
alias
required
string (Alias)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
provider
required
string (Provider)

'google' or 'oidc'

GoogleConfig (object) or null
OIDCConfig (object) or null
ensure_redirects
boolean (Ensure Redirects)
Default: true

Responses

Request samples

Content type
application/json
{
  • "provider": "string",
  • "google": {
    },
  • "oidc": {
    },
  • "ensure_redirects": true
}

Response samples

Content type
application/json
null

Toggle Idp

Authorizations:
OAuth2LoginBearerAuth
path Parameters
alias
required
string (Alias)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
enabled
required
boolean (Enabled)

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
null

Delete Idp

Authorizations:
OAuth2LoginBearerAuth
path Parameters
alias
required
string (Alias)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
null

List Idps

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
null

List Idps Public

Public listing of enabled IdPs (no secrets). Useful for login UI. Returns alias, providerId, enabled, displayName.

Responses

Response samples

Content type
application/json
null

auth-users

List Users

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Resolve User By Identifier

Resolve a user by external_id (Keycloak sub) or local DB id.

Useful for admin UIs that need to display owner information when owner_user_id stores a Keycloak sub rather than a local PK.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
identifier
required
string (Identifier)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "string",
  • "email": "string",
  • "roles": [
    ],
  • "active": true,
  • "deleted": true,
  • "is_external": true,
  • "external_id": "string",
  • "linked_subject_id": "string",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Get User Detail

Authorizations:
OAuth2LoginBearerAuth
path Parameters
user_id
required
string <uuid> (User Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "string",
  • "email": "string",
  • "roles": [
    ],
  • "active": true,
  • "deleted": true,
  • "is_external": true,
  • "external_id": "string",
  • "linked_subject_id": "string",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Update Local

Authorizations:
OAuth2LoginBearerAuth
path Parameters
user_id
required
string <uuid> (User Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Username (string) or Username (null) (Username)
Email (string) or Email (null) (Email)
Active (boolean) or Active (null) (Active)
Array of Roles (strings) or Roles (null) (Roles)

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "email": "string",
  • "active": true,
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "string",
  • "email": "string",
  • "roles": [
    ],
  • "active": true,
  • "deleted": true,
  • "is_external": true,
  • "external_id": "string",
  • "linked_subject_id": "string",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Delete Local

Authorizations:
OAuth2LoginBearerAuth
path Parameters
user_id
required
string <uuid> (User Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "string",
  • "email": "string",
  • "roles": [
    ],
  • "active": true,
  • "deleted": true,
  • "is_external": true,
  • "external_id": "string",
  • "linked_subject_id": "string",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Create Local

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
username
required
string (Username)
Email (string) or Email (null) (Email)
password
required
string (Password)
Array of Roles (strings) or Roles (null) (Roles)

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "email": "string",
  • "password": "string",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "string",
  • "email": "string",
  • "roles": [
    ],
  • "active": true,
  • "deleted": true,
  • "is_external": true,
  • "external_id": "string",
  • "linked_subject_id": "string",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Reset Password

Authorizations:
OAuth2LoginBearerAuth
path Parameters
user_id
required
string <uuid> (User Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
new_password
required
string (New Password)

Responses

Request samples

Content type
application/json
{
  • "new_password": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "string",
  • "email": "string",
  • "roles": [
    ],
  • "active": true,
  • "deleted": true,
  • "is_external": true,
  • "external_id": "string",
  • "linked_subject_id": "string",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Change My Password

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
current_password
required
string (Current Password)
new_password
required
string (New Password)

Responses

Request samples

Content type
application/json
{
  • "current_password": "string",
  • "new_password": "string"
}

Response samples

Content type
application/json
{
  • "changed": true
}

forward-auth

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

path Parameters
path
required
string
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

path Parameters
path
required
string
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

path Parameters
path
required
string
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

path Parameters
path
required
string
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

path Parameters
path
required
string
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

path Parameters
path
required
string
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

Validate

Ingress auth validation endpoint for ForwardAuth / ext_authz callers.

Called by the ingress gateway to authenticate and authorize incoming requests before they reach an upstream service.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Forwarded-Method (string) or X-Forwarded-Method (null) (X-Forwarded-Method)
X-Forwarded-Uri (string) or X-Forwarded-Uri (null) (X-Forwarded-Uri)
X-Forwarded-Host (string) or X-Forwarded-Host (null) (X-Forwarded-Host)
X-Forwarded-Proto (string) or X-Forwarded-Proto (null) (X-Forwarded-Proto)

Responses

Response samples

Content type
application/json
null

auth-tuples

List Relations

Authorizations:
OAuth2LoginBearerAuth
query Parameters
tenant
string (Tenant)
Default: "__default__"

Tenant identifier

Object Namespace (string) or Object Namespace (null) (Object Namespace)

Filter by object namespace

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Diff Relations

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
manifest
required
string (Manifest)
Tenant (string) or Tenant (null) (Tenant)

Responses

Request samples

Content type
application/json
{
  • "manifest": "string",
  • "tenant": "string"
}

Response samples

Content type
application/json
null

Revoke Relations

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
manifest
required
string (Manifest)
Tenant (string) or Tenant (null) (Tenant)
dry_run
boolean (Dry Run)
Default: false

Responses

Request samples

Content type
application/json
{
  • "manifest": "string",
  • "tenant": "string",
  • "dry_run": false
}

Response samples

Content type
application/json
{
  • "tenant": "string",
  • "dry_run": true,
  • "count": 0,
  • "tuples": [
    ]
}

Export Tuple Audit Events

Authorizations:
OAuth2LoginBearerAuth
query Parameters
tenant
string (Tenant)
Default: "__default__"

Tenant identifier

Updated After (string) or Updated After (null) (Updated After)

ISO-8601 timestamp filter (updated_at >= value)

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "tenant": "string",
  • "exported_at": "2019-08-24T14:15:22Z",
  • "count": 0,
  • "events": [
    ]
}

auth-audit

Export Decision Events

Authorizations:
OAuth2LoginBearerAuth
query Parameters
Tenant (string) or Tenant (null) (Tenant)

Filter events to a tenant identifier

Result (string) or Result (null) (Result)

Filter by decision result

Updated After (string) or Updated After (null) (Updated After)

ISO-8601 timestamp filter for decision time

limit
integer (Limit) [ 1 .. 1000 ]
Default: 200

Maximum number of events

Cursor (integer) or Cursor (null) (Cursor)

Resume export from this sequence cursor

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "tenant": "string",
  • "result": "string",
  • "since": "2019-08-24T14:15:22Z",
  • "count": 0,
  • "events": [
    ],
  • "next_cursor": 0,
  • "has_more": true
}

sessions

Revoke Session

Authorizations:
OAuth2LoginBearerAuth
path Parameters
session_id
required
string (Session Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Purge Subject Sessions

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
tenant_id
required
string (Tenant Id)
subject_namespace
string (Subject Namespace)
Default: "user"
subject_id
required
string (Subject Id)

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "string",
  • "subject_namespace": "user",
  • "subject_id": "string"
}

Response samples

Content type
application/json
{
  • "revoked": 0
}

authz

Upsert Tuple

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
required
object (SubjectModel)
relation
required
string (Relation) ^(can_access|cleared_for|connector_operator|e...
required
object (ObjectModel)
Tenant Id (string) or Tenant Id (null) (Tenant Id)

Optional tenant identifier for the relationship

Responses

Request samples

Content type
application/json
{
  • "subject": {
    },
  • "relation": "string",
  • "object": {
    },
  • "tenant_id": "string"
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Tuple

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
required
object (SubjectModel)
Relation (string) or Relation (null) (Relation)
required
object (ObjectModel)
Tenant Id (string) or Tenant Id (null) (Tenant Id)

Optional tenant filter when deleting

Responses

Request samples

Content type
application/json
{
  • "subject": {
    },
  • "relation": "string",
  • "object": {
    },
  • "tenant_id": "string"
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Object Tuples

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
required
object (ObjectModel)
Tenant Id (string) or Tenant Id (null) (Tenant Id)

Optional tenant filter when deleting

Responses

Request samples

Content type
application/json
{
  • "object": {
    },
  • "tenant_id": "string"
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Check Access

Authorizations:
OAuth2LoginBearerAuth
Request Body schema: application/json
required
required
object (SubjectModel)
relation
required
string (Relation) ^(can_access|cleared_for|connector_operator|e...
required
object (ObjectModel)

Responses

Request samples

Content type
application/json
{
  • "subject": {
    },
  • "relation": "string",
  • "object": {
    }
}

Response samples

Content type
application/json
{
  • "allow": true,
  • "decision_id": "string",
  • "reason": "string"
}

models

Get Pending Deployments

Get all models with pending deployment flags and active downloads for UI state recovery.

This endpoint is used by the frontend to recover state after page reloads when download/deploy operations were in progress.

Returns: dict: { "pending_deployments": [model_repo_ids], # Models waiting for deployment "downloading_models": [model_repo_ids], # Models currently downloading "deployment_flags": {model_id: flag_value}, # Raw etcd flags "active_downloads": [download_info], # Detailed download info "total_pending": int, "total_downloading": int }

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{ }

Cleanup Stale Deployments

Manually clean up stale deployment flags in etcd.

This is an admin repair endpoint for platform-level deployment state.

This endpoint removes deployment flags for models that:

  • Have deployment requested (flag = "true")
  • But have no active downloads (is_downloading OR dl_requested_at)
  • And are not currently deployed

Returns: dict: { "cleaned_count": int, "cleaned_flags": [model_ids], "message": str }

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{ }

Get Model Deployment Info

Get deployment information for a deployed model including engine type and port.

Args: model_id (UUID): The ID of the model to get deployment info for

Returns: dict: Deployment information if model is deployed, otherwise {"deployed": false}

Authorizations:
BearerAuthOAuth2Login
path Parameters
model_id
required
string <uuid> (Model Id)

Responses

Response samples

Content type
application/json
{ }

Get Model

Get a model by its id.

Args: model_id (UUID): The id of the model to retrieve.

Returns: Model: The retrieved model.

Raises: HTTPException: If the model is not found.

Authorizations:
BearerAuthOAuth2Login
path Parameters
model_id
required
string <uuid> (Model Id)

Responses

Response samples

Content type
application/json
{
  • "repo_modelId": "string",
  • "modelfamily": "string",
  • "purpose": "string",
  • "name": "string",
  • "version": "string",
  • "author": "string",
  • "source_repository": "string",
  • "sha_repository": "string",
  • "hub": "string",
  • "description": "string",
  • "quantization_details": "string",
  • "private": true,
  • "m_files": [ ],
  • "modelcard": "string",
  • "default_config": { },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "hosted": "local",
  • "created_timestamp": "2019-08-24T14:15:22Z",
  • "modified_timestamp": "2019-08-24T14:15:22Z",
  • "files_being_downloaded": [ ]
}

Delete Model

Delete a model by ID.

Authorization is handled at the service layer via @guarded decorator. The decorator reads request/context from middleware-populated context vars, so no explicit auth params needed here.

When auth is disabled (KAMIWAZA_USE_AUTH=false), the guard is bypassed, allowing direct calls without requester context.

DEV NOTE: This endpoint demonstrates the simplified auth pattern where:

1. AuthContextMiddleware populates context vars on every request

2. Service method uses @guarded decorator for authorization

3. API layer is just routing + response shaping

The guard at the API layer (like the old delete_model_endpoint had) is

now considered anti-pattern - guards belong in the service layer.

Authorizations:
BearerAuthOAuth2Login
path Parameters
model_id
required
string <uuid> (Model Id)
query Parameters
force
boolean (Force)
Default: false

Tear down active deployments instead of refusing deletion (ENG-2279).

Responses

Response samples

Content type
application/json
{ }

Create Model

Create a new model.

Args: model (CreateModel): The model to create.

Returns: Model: The newly created model.

Raises: HTTPException: If there is insufficient disk space to create the model.

Authorizations:
BearerAuthOAuth2Login
query Parameters
force_replace_credentials
boolean (Force Replace Credentials)
Default: false

When the deterministic Catalog secret name for this endpoint is already taken, rotate the existing secret's value in place instead of returning 409. Other models referencing the same URN will pick up the rotated credential.

Request Body schema: application/json
required
Repo Modelid (string) or Repo Modelid (null) (Repo Modelid)
Modelfamily (string) or Modelfamily (null) (Modelfamily)
Purpose (string) or Purpose (null) (Purpose)
name
required
string (Name)
Version (string) or Version (null) (Version)
Author (string) or Author (null) (Author)
Source Repository (string) or Source Repository (null) (Source Repository)
Sha Repository (string) or Sha Repository (null) (Sha Repository)
Hub (string) or Hub (null) (Hub)
Description (string) or Description (null) (Description)
Quantization Details (string) or Quantization Details (null) (Quantization Details)
Private (boolean) or Private (null) (Private)
Array of objects (M Files)
Default: []
Modelcard (string) or Modelcard (null) (Modelcard)
Default Config (object) or Default Config (null) (Default Config)

Responses

Request samples

Content type
application/json
{
  • "repo_modelId": "string",
  • "modelfamily": "string",
  • "purpose": "string",
  • "name": "string",
  • "version": "string",
  • "author": "string",
  • "source_repository": "string",
  • "sha_repository": "string",
  • "hub": "string",
  • "description": "string",
  • "quantization_details": "string",
  • "private": true,
  • "m_files": [ ],
  • "modelcard": "string",
  • "default_config": { }
}

Response samples

Content type
application/json
{
  • "repo_modelId": "string",
  • "modelfamily": "string",
  • "purpose": "string",
  • "name": "string",
  • "version": "string",
  • "author": "string",
  • "source_repository": "string",
  • "sha_repository": "string",
  • "hub": "string",
  • "description": "string",
  • "quantization_details": "string",
  • "private": true,
  • "m_files": [ ],
  • "modelcard": "string",
  • "default_config": { },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "hosted": "local",
  • "created_timestamp": "2019-08-24T14:15:22Z",
  • "modified_timestamp": "2019-08-24T14:15:22Z",
  • "files_being_downloaded": [ ]
}

List Models

Endpoint to list all models, with an option to include associated files.

Args: load_files (bool, optional): Hint to the API to include associated files. Defaults to False.

Returns: List[Model]: A list of models, optionally including their files.

Authorizations:
BearerAuthOAuth2Login
query Parameters
load_files
boolean (Load Files)
Default: false

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Model File

Delete a model file.

Authorization is handled at the service layer via @guarded decorator with an id_resolver that maps model_file_id -> model_id.

Authorizations:
BearerAuthOAuth2Login
path Parameters
model_file_id
required
string <uuid> (Model File Id)

Responses

Response samples

Content type
application/json
{ }

Get Model File

Retrieve a specific model file by its ID.

Args: model_file_id (UUID): The unique identifier of the model file.

Returns: ModelFile: The requested model file.

Raises: HTTPException: An error if the model file is not found.

Authorizations:
BearerAuthOAuth2Login
path Parameters
model_file_id
required
string <uuid> (Model File Id)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "size": 0,
  • "storage_type": "file",
  • "storage_host": "string",
  • "storage_location": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "hub": "string",
  • "model_id": "f8ff2fb8-4acc-4e48-bd83-cbdac23e1224",
  • "checksum": "string",
  • "checksum_type": "string",
  • "created_timestamp": "2019-08-24T14:15:22Z",
  • "is_downloading": true,
  • "download_pid": 0,
  • "download_process_start_time": 0,
  • "download": true,
  • "dl_requested_at": "2019-08-24T14:15:22Z",
  • "download_node": "string",
  • "download_percentage": 0,
  • "download_elapsed": "string",
  • "download_remaining": "string",
  • "download_throughput": "string",
  • "download_cancelled_at": "2019-08-24T14:15:22Z",
  • "storage_digest": "string",
  • "last_push_error": "string",
  • "last_push_error_at": "2019-08-24T14:15:22Z"
}

Search Models

Search for models based on a given search request.

Args: request (ModelSearchRequest): The search criteria for models.

Returns: ModelSearchResponse: Search results with graceful degradation info if hub rate limited.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
query
required
string (Query)
Array of Hubs To Search (strings) or Hubs To Search (null) (Hubs To Search)
Exact (boolean) or Exact (null) (Exact)
Default: false
Limit (integer) or Limit (null) (Limit)
Default: 100

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "hubs_to_search": [
    ],
  • "exact": false,
  • "limit": 100
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total_results": 0,
  • "hub_error": "string",
  • "hub_results_partial": false,
  • "local_results_only": false
}

List Model Files

List all model files.

Returns: List[ModelFile]: A list of all model files.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Model File

Create a new model file.

Args: model_file (CreateModelFile): The model file data to create.

Returns: ModelFile: The created model file.

Raises: HTTPException: An error if there is insufficient disk space to create the model file.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name)

The name of the model file

Size (integer) or Size (null) (Size)

The size of the model file in bytes

StorageType (string) or null

The type of storage where the file is located (file or s3)

storage_host
string (Storage Host)
Default: "localhost"

Host where the file is stored

Storage Location (string) or Storage Location (null) (Storage Location)

The location path or key where the file is stored

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "size": 0,
  • "storage_type": "file",
  • "storage_host": "localhost",
  • "storage_location": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "size": 0,
  • "storage_type": "file",
  • "storage_host": "string",
  • "storage_location": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "hub": "string",
  • "model_id": "f8ff2fb8-4acc-4e48-bd83-cbdac23e1224",
  • "checksum": "string",
  • "checksum_type": "string",
  • "created_timestamp": "2019-08-24T14:15:22Z",
  • "is_downloading": true,
  • "download_pid": 0,
  • "download_process_start_time": 0,
  • "download": true,
  • "dl_requested_at": "2019-08-24T14:15:22Z",
  • "download_node": "string",
  • "download_percentage": 0,
  • "download_elapsed": "string",
  • "download_remaining": "string",
  • "download_throughput": "string",
  • "download_cancelled_at": "2019-08-24T14:15:22Z",
  • "storage_digest": "string",
  • "last_push_error": "string",
  • "last_push_error_at": "2019-08-24T14:15:22Z"
}

Search Hub Model Files

Search for model files in a specific hub based on the given search request.

Args: request (HubModelFileSearch): The search criteria for model files, including hub, model_id, and version.

Returns: List[ModelFile]: A list of model files that match the search criteria.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
hub
required
string (Hub)
model
required
string (Model)
Version (string) or Version (null) (Version)

Responses

Request samples

Content type
application/json
{
  • "hub": "string",
  • "model": "string",
  • "version": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Download Model

Download specified files associated with a model

Args: request (ModelDownloadRequest): A payload specifying model_id, version, hub, and files_to_download

Returns: dict: A dictionary containing the download status of the model files. The dictionary has the following keys: - 'result': A boolean indicating whether the download was successfully initiated or not. - 'message': A string containing a message about the download status. - 'files': A list of modelfile ids being downloaded

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
model
required
string (Model)
Version (string) or Version (null) (Version)
Hub (string) or Hub (null) (Hub)
Array of Files To Download (strings) or Files To Download (null) (Files To Download)
Deploy After Download (boolean) or Deploy After Download (null) (Deploy After Download)
Default: true
Novice Selected Context (integer) or Novice Selected Context (null) (Novice Selected Context)
Deployment Target (string) or Deployment Target (null) (Deployment Target)

Responses

Request samples

Content type
application/json
{
  • "model": "string",
  • "version": "string",
  • "hub": "string",
  • "files_to_download": [
    ],
  • "deploy_after_download": true,
  • "novice_selected_context": 0,
  • "deployment_target": "string"
}

Response samples

Content type
application/json
{ }

Create Model Configuration

Create a new model configuration.

Authorizations:
BearerAuthOAuth2Login
query Parameters
force_replace_credentials
boolean (Force Replace Credentials)
Default: false

Rotate the existing Catalog secret value in place if the deterministic name collides. See POST /models/.

Request Body schema: application/json
required
m_id
required
string <uuid> (M Id)

Foreign key to the associated model

M File Id (string) or M File Id (null) (M File Id)

Foreign key to the associated model file

Name (string) or Name (null) (Name)

Name of the model configuration

default
required
boolean (Default)

Whether this is the default model configuration for the model

Description (string) or Description (null) (Description)

Description of the model configuration and purpose

object (Config)

Key-value pairs for model configuration parameters

object (System Config)

Key-value pairs for system configuration parameters

Responses

Request samples

Content type
application/json
{
  • "m_id": "9fa8614b-5eb2-4338-b373-8a5898e84e27",
  • "m_file_id": "4ac4c186-075b-4681-9464-7d9e843ec833",
  • "name": "string",
  • "default": true,
  • "description": "string",
  • "config": { },
  • "system_config": { }
}

Response samples

Content type
application/json
{
  • "m_id": "9fa8614b-5eb2-4338-b373-8a5898e84e27",
  • "m_file_id": "4ac4c186-075b-4681-9464-7d9e843ec833",
  • "name": "string",
  • "default": true,
  • "description": "string",
  • "config": { },
  • "system_config": { },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "kamiwaza_version": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "modified_at": "2019-08-24T14:15:22Z"
}

List Model Configurations

List all model configurations associated with a given model ID.

Authorizations:
BearerAuthOAuth2Login
query Parameters
model_id
required
string <uuid> (Model Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a List of Model Configurations for the Model

Get a list of model configurations for a given model ID.

Authorizations:
BearerAuthOAuth2Login
path Parameters
model_id
required
string <uuid> (Model Id)
query Parameters
default
boolean (Default)
Default: false

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Model Configuration

Get a model configuration by its ID.

Authorizations:
BearerAuthOAuth2Login
path Parameters
model_config_id
required
string <uuid> (Model Config Id)

Responses

Response samples

Content type
application/json
{
  • "m_id": "9fa8614b-5eb2-4338-b373-8a5898e84e27",
  • "m_file_id": "4ac4c186-075b-4681-9464-7d9e843ec833",
  • "name": "string",
  • "default": true,
  • "description": "string",
  • "config": { },
  • "system_config": { },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "kamiwaza_version": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "modified_at": "2019-08-24T14:15:22Z"
}

Delete Model Configuration

Delete a model configuration by its ID.

Authorizations:
BearerAuthOAuth2Login
path Parameters
model_config_id
required
string <uuid> (Model Config Id)

Responses

Response samples

Content type
application/json
{ }

Update Model Configuration

Update a model configuration by its ID.

Authorizations:
BearerAuthOAuth2Login
path Parameters
model_config_id
required
string <uuid> (Model Config Id)
query Parameters
force_replace_credentials
boolean (Force Replace Credentials)
Default: false

Rotate the existing Catalog secret value in place if the deterministic name collides. See POST /models/.

Request Body schema: application/json
required
m_id
required
string <uuid> (M Id)

Foreign key to the associated model

M File Id (string) or M File Id (null) (M File Id)

Foreign key to the associated model file

Name (string) or Name (null) (Name)

Name of the model configuration

default
required
boolean (Default)

Whether this is the default model configuration for the model

Description (string) or Description (null) (Description)

Description of the model configuration and purpose

object (Config)

Key-value pairs for model configuration parameters

object (System Config)

Key-value pairs for system configuration parameters

Responses

Request samples

Content type
application/json
{
  • "m_id": "9fa8614b-5eb2-4338-b373-8a5898e84e27",
  • "m_file_id": "4ac4c186-075b-4681-9464-7d9e843ec833",
  • "name": "string",
  • "default": true,
  • "description": "string",
  • "config": { },
  • "system_config": { }
}

Response samples

Content type
application/json
{
  • "m_id": "9fa8614b-5eb2-4338-b373-8a5898e84e27",
  • "m_file_id": "4ac4c186-075b-4681-9464-7d9e843ec833",
  • "name": "string",
  • "default": true,
  • "description": "string",
  • "config": { },
  • "system_config": { },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "kamiwaza_version": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "modified_at": "2019-08-24T14:15:22Z"
}

Get Model Memory Usage

Get the memory usage of a model.

Authorizations:
BearerAuthOAuth2Login
path Parameters
model_id
required
string <uuid> (Model Id)

Responses

Response samples

Content type
application/json
0
0

Get Model File Memory Usage

Get the memory usage of a model file.

Authorizations:
BearerAuthOAuth2Login
path Parameters
model_file_id
required
string <uuid> (Model File Id)

Responses

Response samples

Content type
application/json
0
0

Get Model Files Download Status

Get the download status of specified model files.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "model_ids": [
    ]
}

Cancel Model Download

Cancel a model download.

Authorizations:
BearerAuthOAuth2Login
path Parameters
model_file_id
required
string <uuid> (Model File Id)

Responses

Response samples

Content type
application/json
{
  • "result": true,
  • "message": "string",
  • "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
  • "cancelled_at": "2019-08-24T14:15:22Z"
}

Cancel All Downloads

Cancel all currently downloading model files, optionally filtered by model

Args: model_id: Optional model ID to filter downloads. If provided, only cancels downloads for that model

Returns: BulkDownloadCancelResponse: Status of the bulk cancellation operation

Authorizations:
BearerAuthOAuth2Login
query Parameters
Model Id (string) or Model Id (null) (Model Id)

Optional model ID to filter cancellation to a specific model

Responses

Response samples

Content type
application/json
{
  • "result": true,
  • "message": "string",
  • "total_downloads": 0,
  • "cancelled_count": 0,
  • "failed_count": 0,
  • "cancelled_files": [ ],
  • "failed_files": [ ],
  • "cancelled_at": "2019-08-24T14:15:22Z"
}

Download And Deploy Model

Download model files and set deployment flag for automatic deployment after completion.

Args: request (ModelDownloadRequest): A payload specifying model_id, version, hub, and files_to_download

Returns: dict: Download status with deployment flag set

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
model
required
string (Model)
Version (string) or Version (null) (Version)
Hub (string) or Hub (null) (Hub)
Array of Files To Download (strings) or Files To Download (null) (Files To Download)
Deploy After Download (boolean) or Deploy After Download (null) (Deploy After Download)
Default: true
Novice Selected Context (integer) or Novice Selected Context (null) (Novice Selected Context)
Deployment Target (string) or Deployment Target (null) (Deployment Target)

Responses

Request samples

Content type
application/json
{
  • "model": "string",
  • "version": "string",
  • "hub": "string",
  • "files_to_download": [
    ],
  • "deploy_after_download": true,
  • "novice_selected_context": 0,
  • "deployment_target": "string"
}

Response samples

Content type
application/json
{ }

Deploy After Download

Check if model downloads are complete and deploy if ready.

Args: model_key (Union[UUID, str]): The ID or repo_modelId of the model to check and deploy request (Optional[dict]): Optional request body with novice_selected_context and files_to_deploy

Returns: dict: Deployment status

Authorizations:
BearerAuthOAuth2Login
path Parameters
required
Model Key (string) or Model Key (string) (Model Key)
Request Body schema: application/json
Any of
property name*
additional property
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
{ }

Get Model Guides

Get all model guide entries.

Returns: List[ModelGuide]: List of all model guide entries.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Import Model Guide

Import model guide data from the default JSON file. This endpoint will load guide/default/models.json and import all entries.

Args: replace: If True, delete all existing guides before importing. Default is False.

Returns: dict: A message indicating the import status.

Authorizations:
BearerAuthOAuth2Login
query Parameters
replace
boolean (Replace)
Default: false

Responses

Response samples

Content type
application/json
{ }

Refresh Model Guide

Refresh model guide data from external endpoint. This endpoint will fetch the latest guide data from Kamiwaza infrastructure.

Returns: dict: A message indicating the refresh status.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{ }

config

Get Routing Config

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "mode": "path",
  • "base_host": "cluster.local",
  • "service_prefixes": {
    },
  • "enabled_services": {
    },
  • "updated_at": "string"
}

Get Routing Config

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "mode": "path",
  • "base_host": "cluster.local",
  • "service_prefixes": {
    },
  • "enabled_services": {
    },
  • "updated_at": "string"
}

Patch Routing Config

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
Base Host (string) or Base Host (null) (Base Host)

Base hostname override

Service Prefixes (object) or Service Prefixes (null) (Service Prefixes)

Service prefix overrides

Enabled Services (object) or Enabled Services (null) (Enabled Services)

Service enable/disable overrides

Responses

Request samples

Content type
application/json
{
  • "base_host": "cluster.local",
  • "service_prefixes": {
    },
  • "enabled_services": {
    }
}

Response samples

Content type
application/json
{
  • "mode": "path",
  • "base_host": "cluster.local",
  • "service_prefixes": {
    },
  • "enabled_services": {
    },
  • "updated_at": "string"
}

Patch Routing Config

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
Base Host (string) or Base Host (null) (Base Host)

Base hostname override

Service Prefixes (object) or Service Prefixes (null) (Service Prefixes)

Service prefix overrides

Enabled Services (object) or Enabled Services (null) (Enabled Services)

Service enable/disable overrides

Responses

Request samples

Content type
application/json
{
  • "base_host": "cluster.local",
  • "service_prefixes": {
    },
  • "enabled_services": {
    }
}

Response samples

Content type
application/json
{
  • "mode": "path",
  • "base_host": "cluster.local",
  • "service_prefixes": {
    },
  • "enabled_services": {
    },
  • "updated_at": "string"
}

Get Runtime Posture

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "developerDiagnosticsEnabled": false,
  • "environment": "",
  • "authMode": "unknown",
  • "images": {
    }
}

Get Runtime Posture

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "developerDiagnosticsEnabled": false,
  • "environment": "",
  • "authMode": "unknown",
  • "images": {
    }
}

serving

Start Ray

Admin-gated HTTP wrapper for starting Ray.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Address (string) or Address (null) (Address)
Request Body schema: application/json
Runtime Env (object) or Runtime Env (null) (Runtime Env)
Options (object) or Options (null) (Options)

Responses

Request samples

Content type
application/json
{
  • "runtime_env": { },
  • "options": { }
}

Response samples

Content type
application/json
null

Upsert Greymatter Route Intent

Internal API for controllers to submit generated Greymatter route intents.

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Kamiwaza-Route-Intent-Token (string) or X-Kamiwaza-Route-Intent-Token (null) (X-Kamiwaza-Route-Intent-Token)
Request Body schema: application/json
required
route_id
required
string (Route Id)

Stable generated route id

owner_kind
required
string (Owner Kind)

Source object kind, e.g. extension

owner_id
required
string (Owner Id)

Source object id

public_path
required
string (Public Path)

External path prefix

required
object (GreymatterRouteBackendRequest)

Backend service target that Greymatter should route to

Rewrite Path (string) or Rewrite Path (null) (Rewrite Path)

Optional upstream rewrite path

auth_mode
string (RouteAuthMode)
Default: "protected"
Enum: "protected" "bypass"

Whether the route is protected by gateway auth

object (Headers)

Request headers injected by the gateway route

Responses

Request samples

Content type
application/json
{
  • "route_id": "string",
  • "owner_kind": "string",
  • "owner_id": "string",
  • "public_path": "string",
  • "backend": {
    },
  • "rewrite_path": "string",
  • "auth_mode": "protected",
  • "headers": {
    }
}

Response samples

Content type
application/json
{
  • "route_id": "string",
  • "state": "string",
  • "commit_sha": "string",
  • "reason": ""
}

Delete Greymatter Route Intent

Internal API for controllers to remove generated Greymatter route intents.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
route_id
required
string (Route Id) ^[A-Za-z0-9_.-]+$
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Kamiwaza-Route-Intent-Token (string) or X-Kamiwaza-Route-Intent-Token (null) (X-Kamiwaza-Route-Intent-Token)

Responses

Response samples

Content type
application/json
{
  • "route_id": "string",
  • "state": "string",
  • "commit_sha": "string",
  • "reason": ""
}

Get Status

Get the status of Ray. Returns a dictionary with the status of Ray.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
null

Estimate Model Vram

Estimate the VRAM required for a model deployment. If Ray is initialized, runs estimation on the node with the model files. Otherwise falls back to local estimation.

Leverages globalizer to distribute to the correct node.

Args: deployment_request (CreateModelDeployment): The deployment request containing model configuration.

Returns: Dict[str, float]: A dictionary containing the computed VRAM estimate and the highest node VRAM.

Raises: HTTPException: If the model is not found or estimation fails.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
m_id
required
string <uuid> (M Id)

The UUID of the model to deploy

M File Id (string) or M File Id (null) (M File Id)

Which weights file to use for models with >1 set of weights (eg, multi-quant GPTQ models)

m_config_id
required
string <uuid> (M Config Id)

The UUID of the ModelConfig to use for this deployment

Engine Name (string) or Engine Name (null) (Engine Name)

Name of the engine to use for deployment

Duration (integer) or Duration (null) (Duration)

Duration in minutes for which the model should be deployed; default indefinite

min_copies
integer (Min Copies)
Default: 1

Minimum number of copies to maintain; if set to 0 will dynamically reactivate

starting_copies
integer (Starting Copies)
Default: 1

Number of copies to start with

Max Copies (integer) or Max Copies (null) (Max Copies)

Maximum number of copies allowed

Location (string) or Location (null) (Location)

Location where the model is to be deployed

lb_port
integer (Lb Port)
Default: 0

Port on which the load balancer is listening

autoscaling
boolean (Autoscaling)
Default: false

Whether autoscaling is enabled

force_cpu
boolean (Force Cpu)
Default: false

Whether to force CPU usage; not required on Ampere systems without accelerators; otherwise expected for cpu deployment

Node Resource Type (string) or Node Resource Type (null) (Node Resource Type)

The specialized gpu node resource; for future use for mixed clusters

Max Concurrent Requests (integer) or Max Concurrent Requests (null) (Max Concurrent Requests)

Maximum number of concurrent requests allowed

Vram Allocation (number) or Vram Allocation (null) (Vram Allocation)

Optional explicit override of the VRAM allocation, in bytes of vram for each copy of the deployed model. When omitted, the platform computes it from the VRAM estimate. An explicit value is honored on both the profiled and estimate-unavailable paths; on the estimate-unavailable path it is honored only alongside an explicit gpu_allocation (gpu_allocation is what makes the deployment schedulable). Because it is byte-denominated, a value below 1 byte is ignored rather than truncated to 0.

Gpu Allocation (number) or Gpu Allocation (null) (Gpu Allocation)

Optional explicit override of the GPU allocation, as a fraction of a node GPU for ray serve allocation. When omitted, the platform computes it from the VRAM estimate. An explicit value is honored even when the estimate is unavailable (e.g. an unprofiled model), so it can be used to deploy a model the platform cannot size automatically. A value of 0 means CPU.

active_req_per_replica
integer (Active Req Per Replica)
Default: 20

Number of active requests per replica

M Version (string) or M Version (null) (M Version)

Version of the model

engine
string (Engine)
Default: "vllm"

Engine to use for deployment

container
string (Container)
Default: "kamiwaza"

Container to use for deployment

Deployment Target (string) or Deployment Target (null) (Deployment Target)

Target environment: 'auto' (default), 'host', 'docker', 'k8s'. Controls where inference runs.

Runtime Env (object) or Runtime Env (null) (Runtime Env)

ENG-4068: per-deployment runtime environment overrides. Highest precedence layer above admin overrides and the platform GPU cascade. Keys are env var names. Values are strings (set), or null (suppress a lower-layer key). Reserved keys (LD_LIBRARY_PATH, etc.) are adapter-owned and cannot be set from this layer; attempts log at WARN and are dropped.

Responses

Request samples

Content type
application/json
{
  • "autoscaling": false,
  • "engine_name": "vllm",
  • "lb_port": 0,
  • "m_config_id": "22222222-2222-2222-2222-222222222222",
  • "m_id": "11111111-1111-1111-1111-111111111111",
  • "max_copies": 2,
  • "min_copies": 1,
  • "starting_copies": 1
}

Response samples

Content type
application/json
{ }

Deploy Model

Deploy a model asynchronously (ENG-6530): respond 202 Accepted with the deployment id as soon as the deployment record is created and the launch is kicked off in background. The body is the bare UUID existing clients already parse. Poll GET /serving/deployments for progress; launch failures land on the row as a terminal status with last_error_message. Validation/admission errors raised before the record exists still fail this request synchronously.

Args: create_model_request (CreateModelDeployment): The deployment request containing model configuration.

Returns: Union[UUID, bool]: The UUID of the accepted deployment. Failures before the record exists never return False to the client — they raise HTTPException (404/409/5xx) from this route instead; the bool in the response model is legacy contract surface only.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
m_id
required
string <uuid> (M Id)

The UUID of the model to deploy

M File Id (string) or M File Id (null) (M File Id)

Which weights file to use for models with >1 set of weights (eg, multi-quant GPTQ models)

m_config_id
required
string <uuid> (M Config Id)

The UUID of the ModelConfig to use for this deployment

Engine Name (string) or Engine Name (null) (Engine Name)

Name of the engine to use for deployment

Duration (integer) or Duration (null) (Duration)

Duration in minutes for which the model should be deployed; default indefinite

min_copies
integer (Min Copies)
Default: 1

Minimum number of copies to maintain; if set to 0 will dynamically reactivate

starting_copies
integer (Starting Copies)
Default: 1

Number of copies to start with

Max Copies (integer) or Max Copies (null) (Max Copies)

Maximum number of copies allowed

Location (string) or Location (null) (Location)

Location where the model is to be deployed

lb_port
integer (Lb Port)
Default: 0

Port on which the load balancer is listening

autoscaling
boolean (Autoscaling)
Default: false

Whether autoscaling is enabled

force_cpu
boolean (Force Cpu)
Default: false

Whether to force CPU usage; not required on Ampere systems without accelerators; otherwise expected for cpu deployment

Node Resource Type (string) or Node Resource Type (null) (Node Resource Type)

The specialized gpu node resource; for future use for mixed clusters

Max Concurrent Requests (integer) or Max Concurrent Requests (null) (Max Concurrent Requests)

Maximum number of concurrent requests allowed

Vram Allocation (number) or Vram Allocation (null) (Vram Allocation)

Optional explicit override of the VRAM allocation, in bytes of vram for each copy of the deployed model. When omitted, the platform computes it from the VRAM estimate. An explicit value is honored on both the profiled and estimate-unavailable paths; on the estimate-unavailable path it is honored only alongside an explicit gpu_allocation (gpu_allocation is what makes the deployment schedulable). Because it is byte-denominated, a value below 1 byte is ignored rather than truncated to 0.

Gpu Allocation (number) or Gpu Allocation (null) (Gpu Allocation)

Optional explicit override of the GPU allocation, as a fraction of a node GPU for ray serve allocation. When omitted, the platform computes it from the VRAM estimate. An explicit value is honored even when the estimate is unavailable (e.g. an unprofiled model), so it can be used to deploy a model the platform cannot size automatically. A value of 0 means CPU.

active_req_per_replica
integer (Active Req Per Replica)
Default: 20

Number of active requests per replica

M Version (string) or M Version (null) (M Version)

Version of the model

engine
string (Engine)
Default: "vllm"

Engine to use for deployment

container
string (Container)
Default: "kamiwaza"

Container to use for deployment

Deployment Target (string) or Deployment Target (null) (Deployment Target)

Target environment: 'auto' (default), 'host', 'docker', 'k8s'. Controls where inference runs.

Runtime Env (object) or Runtime Env (null) (Runtime Env)

ENG-4068: per-deployment runtime environment overrides. Highest precedence layer above admin overrides and the platform GPU cascade. Keys are env var names. Values are strings (set), or null (suppress a lower-layer key). Reserved keys (LD_LIBRARY_PATH, etc.) are adapter-owned and cannot be set from this layer; attempts log at WARN and are dropped.

Responses

Request samples

Content type
application/json
{
  • "autoscaling": false,
  • "engine_name": "vllm",
  • "lb_port": 0,
  • "m_config_id": "22222222-2222-2222-2222-222222222222",
  • "m_id": "11111111-1111-1111-1111-111111111111",
  • "max_copies": 2,
  • "min_copies": 1,
  • "starting_copies": 1
}

Response samples

Content type
application/json
true

List Deployments

List all model deployments, optionally filtered by model_id and/or capability.

Performs an opportunistic health check to ensure deployment statuses are up-to-date before returning the list, so users see current status without waiting for the background scheduler.

Args: model_id (Optional[UUID]): The ID of the model to filter deployments by. capability (Optional[List[str]]): One or more capabilities. Pass as repeated query params — ?capability=chat&capability=transcribe returns deployments serving either. Supported values are listed in engine_selector.KNOWN_CAPABILITIES. Unknown values 422.

Returns: List[UIModelDeployment]: A list of model deployments with current status.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Model Id (string) or Model Id (null) (Model Id)
Array of Capability (strings) or Capability (null) (Capability)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Deployment

Get the details of a specific model deployment.

Args: deployment_id (UUID): The ID of the deployment.

Returns: UIModelDeployment: The details of the specified deployment.

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)

Responses

Response samples

Content type
application/json
{
  • "autoscaling": false,
  • "engine_name": "vllm",
  • "lb_port": 0,
  • "m_config_id": "22222222-2222-2222-2222-222222222222",
  • "m_id": "11111111-1111-1111-1111-111111111111",
  • "max_copies": 2,
  • "min_copies": 1,
  • "starting_copies": 1
}

Stop Deployment

Admin-only HTTP wrapper for shared model deployment teardown.

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)
query Parameters
force
boolean (Force)
Default: false

Responses

Response samples

Content type
application/json
true

Delete Deployment

Admin-only hard delete for deployment records.

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)
query Parameters
force
boolean (Force)
Default: false

Responses

Response samples

Content type
application/json
true

Get Deployment Status

Get the status of a specific model deployment.

Args: deployment_id (UUID): The ID of the deployment.

Returns: ModelDeployment: The status of the specified deployment.

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)

Responses

Response samples

Content type
application/json
"string"

List Model Instances

List all model instances, optionally filtered by deployment ID.

Args: deployment_id (Optional[UUID]): The ID of the deployment to filter instances by. Defaults to None.

Returns: List[ModelInstance]: A list of all model instances currently active, optionally filtered by deployment ID.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Deployment Id (string) or Deployment Id (null) (Deployment Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Model Instance

Retrieve a specific model instance by its ID.

Args: instance_id (UUID): The ID of the model instance to retrieve.

Returns: ModelInstance: The model instance if found, otherwise raises a 404 HTTPException.

Authorizations:
BearerAuthOAuth2Login
path Parameters
instance_id
required
string <uuid> (Instance Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "deployment_id": "6ef0ac85-9892-4664-a2a5-58bf2af5a8a6",
  • "deployed_at": "2019-08-24T14:15:22Z",
  • "container_id": "string",
  • "node_id": "6e0bdcac-9717-4a6f-972e-97489dffeb0c",
  • "host_name": "string",
  • "files_synced": true,
  • "listen_port": 0,
  • "status": "UNINITIALIZED",
  • "extra_details": { }
}

Health

Get the health of all model deployments.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Deployment Logs

Get container logs for a specific deployment. Returns captured logs from the inference container with metadata.

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)

Responses

Response samples

Content type
application/json
{
  • "deployment_id": "6ef0ac85-9892-4664-a2a5-58bf2af5a8a6",
  • "engine_type": "string",
  • "container_id": "string",
  • "log_file_path": "string",
  • "logs": [
    ],
  • "total_lines_seen": 0,
  • "current_lines_stored": 0,
  • "compressed": true,
  • "capture_active": true
}

Get Deployment Log Patterns

Analyze container logs for failure patterns (OOM, CUDA errors, etc.).

This endpoint returns pattern analysis for informational purposes only. It does NOT update deployment status - that should only be done based on actual container/service state, not log analysis.

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)

Responses

Response samples

Content type
application/json
{
  • "deployment_id": "6ef0ac85-9892-4664-a2a5-58bf2af5a8a6",
  • "patterns_detected": {
    },
  • "failure_lines": [
    ],
  • "analysis_timestamp": "2019-08-24T14:15:22Z"
}

List Engine Logs

List available container logs for a specific engine type (vllm, llamacpp, etc.).

Authorizations:
BearerAuthOAuth2Login
path Parameters
engine_type
required
string (Engine Type)

Responses

Response samples

Content type
application/json
{
  • "engine_type": "string",
  • "logs": [
    ]
}

Discover External Endpoint Route

Probe an OpenAI-compatible provider and return its advertised model list.

Credentials supplied via api_key are used only for this probe and discarded. Credentials supplied via credential_secret_urn are resolved server-side through CatalogService — the plaintext never round-trips through the client. Gated at AuthenticatedUser to match the sibling create_model path that actually persists registrations; tightening this surface coherently is tracked separately.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
base_url
required
string <uri> (Base Url) [ 1 .. 2083 ] characters

Provider base URL. For Azure hosts the probe hits the data-plane deployments-listing route; for everything else, /v1/models.

Api Key (string) or Api Key (null) (Api Key)

Bearer token used only for this probe; not persisted.

Credential Secret Urn (string) or Credential Secret Urn (null) (Credential Secret Urn)

Reference to an already-stored Catalog secret. The route handler resolves this server-side (CatalogService.get_secret_value) and uses the resulting plaintext to probe the provider — the URN value never round-trips through the client.

Provider (string) or Provider (null) (Provider)

Vendor the operator selected in the wizard. Lets discovery honor that choice for a host the URL-suffix map can't classify — e.g. an Azure inference proxy on a private/sovereign network is probed as Azure instead of falling back to the generic /v1/models path. Optional; when unset the strategy is derived from the URL alone.

Responses

Request samples

Content type
application/json
{
  • "base_url": "http://example.com",
  • "api_key": "string",
  • "credential_secret_urn": "string",
  • "provider": "azure"
}

Response samples

Content type
application/json
{
  • "available_models": [
    ]
}

vectordb

Get Vectordbs

Compatibility endpoint for legacy VectorDB API callers.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Engine (string) or Engine (null) (Engine)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

dataset-gate-binding

Set Dataset Attribute Gate

T2.5: bind an AttributeGate to a dataset.

Auth (M3 Proactive Security Checklist §4.4.3.1):

  • NativeRealmRequired: mesh-origin rejected.
  • Owner-on-dataset ReBAC: only the dataset's owner (per ReBAC relations) can rebind its gate. Closes the privilege-escalation gap where any admin could rewrite any other admin's dataset gate.

Side effects:

  • Validates type is an AttributeGate subclass (else 400 wrong_kind).
  • Validates config against gate.config_schema() (T2.6).
  • Writes properties.gate = {type, config} via the configured DatasetGateStore (T2.7).
  • Invalidates the discover cache (v0.3.5 OQ-10).
  • Emits gate_binding/set audit event with dataset_urn (T2.12).
Authorizations:
BearerAuthOAuth2Login
path Parameters
urn
required
string (Urn)
Request Body schema: application/json
required
type
required
string (Type)
object (Config)
Default: {}

Responses

Request samples

Content type
application/json
{
  • "type": "string",
  • "config": { }
}

Response samples

Content type
application/json
{
  • "dataset_urn": "string",
  • "type": "string",
  • "config": { },
  • "gate_name": "string",
  • "kind": "string"
}

Get Dataset Attribute Gate

T2.5: read the active AttributeGate binding for a dataset.

Auth: viewer or owner on dataset:{urn} (ReBAC). Symmetric with workrooms/api.py's get_workroom shape.

Returns 404 not_configured when the dataset exists but has no gate, and 404 dataset_not_found when the URN itself is unknown. Distinguishing these matters for SDK callers — the first is a "no policy yet" signal, the second is a typo.

Authorizations:
BearerAuthOAuth2Login
path Parameters
urn
required
string (Urn)

Responses

Response samples

Content type
application/json
{
  • "dataset_urn": "string",
  • "type": "string",
  • "config": { },
  • "gate_name": "string",
  • "kind": "string"
}

Delete Dataset Attribute Gate

T2.5: clear a dataset's AttributeGate binding.

Auth: owner on dataset:{urn} (ReBAC) + NativeRealmRequired.

Authorizations:
BearerAuthOAuth2Login
path Parameters
urn
required
string (Urn)

Responses

Response samples

Content type
application/json
{ }

catalog

Health Check

Simple health check endpoint.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
null

Health Check

Simple health check endpoint.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
null

Create Dataset

Create a new dataset.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name)
platform
required
string (Platform)
environment
string (Environment)
Default: "PROD"
Description (string) or Description (null) (Description)
tags
Array of strings (Tags)
Default: []
object (Properties)
Default: {}
Schema (object) or null
Container Urn (string) or Container Urn (null) (Container Urn)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string"
}

Response samples

Content type
application/json
"string"

Create Dataset

Create a new dataset.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name)
platform
required
string (Platform)
environment
string (Environment)
Default: "PROD"
Description (string) or Description (null) (Description)
tags
Array of strings (Tags)
Default: []
object (Properties)
Default: {}
Schema (object) or null
Container Urn (string) or Container Urn (null) (Container Urn)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string"
}

Response samples

Content type
application/json
"string"

List Datasets

List datasets, optionally filtering by query or other properties.

When ReBAC is enabled, results are filtered to the datasets that are canonically visible to the caller under the resolved requester and workroom posture, regardless of caller origin.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Query (string) or Query (null) (Query)

Search query string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Datasets

List datasets, optionally filtering by query or other properties.

When ReBAC is enabled, results are filtered to the datasets that are canonically visible to the caller under the resolved requester and workroom posture, regardless of caller origin.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Query (string) or Query (null) (Query)

Search query string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Dataset By Urn

Get dataset by URN using query parameter.

RECOMMENDED for complex URNs with forward slashes. Example: GET /catalog/datasets/by-urn?urn=urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Dataset URN

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Dataset By Urn

Get dataset by URN using query parameter.

RECOMMENDED for complex URNs with forward slashes. Example: GET /catalog/datasets/by-urn?urn=urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Dataset URN

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Dataset By Urn

Update dataset by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Dataset URN

Request Body schema: application/json
required
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Container Urn (string) or Container Urn (null) (Container Urn)
Updated At (string) or Updated At (null) (Updated At)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "container_urn": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Dataset By Urn

Update dataset by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Dataset URN

Request Body schema: application/json
required
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Container Urn (string) or Container Urn (null) (Container Urn)
Updated At (string) or Updated At (null) (Updated At)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "container_urn": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Dataset By Urn

Delete dataset by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Dataset URN

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Dataset By Urn

Delete dataset by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Dataset URN

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Schema By Urn

Get schema by URN using query parameter.

RECOMMENDED for complex URNs with forward slashes. Example: GET /catalog/datasets/by-urn/schema?urn=urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Dataset URN

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "version": 0,
  • "fields": [
    ]
}

Get Schema By Urn

Get schema by URN using query parameter.

RECOMMENDED for complex URNs with forward slashes. Example: GET /catalog/datasets/by-urn/schema?urn=urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Dataset URN

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "version": 0,
  • "fields": [
    ]
}

Update Schema By Urn

Update schema by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Dataset URN

Request Body schema: application/json
required
name
required
string (Name)
platform
required
string (Platform)
Version (integer) or Version (null) (Version)
required
Array of objects (Fields)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "version": 0,
  • "fields": [
    ]
}

Response samples

Content type
application/json
null

Update Schema By Urn

Update schema by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Dataset URN

Request Body schema: application/json
required
name
required
string (Name)
platform
required
string (Platform)
Version (integer) or Version (null) (Version)
required
Array of objects (Fields)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "version": 0,
  • "fields": [
    ]
}

Response samples

Content type
application/json
null

Get Dataset V2

Get dataset by URN using regex-based path converter (V2 - RECOMMENDED).

This endpoint properly handles DataHub URNs with forward slashes using custom regex matching. Supports all URN complexities while maintaining clean RESTful URLs.

Example: GET /catalog/datasets/v2/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Dataset V2

Get dataset by URN using regex-based path converter (V2 - RECOMMENDED).

This endpoint properly handles DataHub URNs with forward slashes using custom regex matching. Supports all URN complexities while maintaining clean RESTful URLs.

Example: GET /catalog/datasets/v2/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Dataset V2

Update dataset by URN using regex-based path converter (V2 - RECOMMENDED).

Example: PATCH /catalog/datasets/v2/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)
Request Body schema: application/json
required
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Container Urn (string) or Container Urn (null) (Container Urn)
Updated At (string) or Updated At (null) (Updated At)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "container_urn": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Dataset V2

Update dataset by URN using regex-based path converter (V2 - RECOMMENDED).

Example: PATCH /catalog/datasets/v2/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)
Request Body schema: application/json
required
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Container Urn (string) or Container Urn (null) (Container Urn)
Updated At (string) or Updated At (null) (Updated At)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "container_urn": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Dataset V2

Delete dataset by URN using regex-based path converter (V2 - RECOMMENDED).

Example: DELETE /catalog/datasets/v2/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Dataset V2

Delete dataset by URN using regex-based path converter (V2 - RECOMMENDED).

Example: DELETE /catalog/datasets/v2/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Schema V2

Get schema by URN using regex-based path converter (V2 - RECOMMENDED).

This endpoint properly handles DataHub URNs with forward slashes including sub-resources.

Example: GET /catalog/datasets/v2/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)/schema

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "version": 0,
  • "fields": [
    ]
}

Get Schema V2

Get schema by URN using regex-based path converter (V2 - RECOMMENDED).

This endpoint properly handles DataHub URNs with forward slashes including sub-resources.

Example: GET /catalog/datasets/v2/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)/schema

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "version": 0,
  • "fields": [
    ]
}

Update Schema V2

Update schema by URN using regex-based path converter (V2 - RECOMMENDED).

Example: PUT /catalog/datasets/v2/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)/schema

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)
Request Body schema: application/json
required
name
required
string (Name)
platform
required
string (Platform)
Version (integer) or Version (null) (Version)
required
Array of objects (Fields)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "version": 0,
  • "fields": [
    ]
}

Response samples

Content type
application/json
null

Update Schema V2

Update schema by URN using regex-based path converter (V2 - RECOMMENDED).

Example: PUT /catalog/datasets/v2/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)/schema

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)
Request Body schema: application/json
required
name
required
string (Name)
platform
required
string (Platform)
Version (integer) or Version (null) (Version)
required
Array of objects (Fields)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "version": 0,
  • "fields": [
    ]
}

Response samples

Content type
application/json
null

Get Dataset

Get dataset by URN in path (BACKWARD COMPATIBLE).

NOTE: URNs with forward slashes should use /by-urn endpoint instead. For path usage, ensure proper URL encoding:

  • Single encode: %2F for /
  • May require double encoding for complex URNs: %252F

Example: GET /catalog/datasets/urn%3Ali%3Adataset%3A(urn%3Ali%3AdataPlatform%3Afile%2Csimple-name%2CPROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Dataset

Get dataset by URN in path (BACKWARD COMPATIBLE).

NOTE: URNs with forward slashes should use /by-urn endpoint instead. For path usage, ensure proper URL encoding:

  • Single encode: %2F for /
  • May require double encoding for complex URNs: %252F

Example: GET /catalog/datasets/urn%3Ali%3Adataset%3A(urn%3Ali%3AdataPlatform%3Afile%2Csimple-name%2CPROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Dataset

Update dataset by URN in path (BACKWARD COMPATIBLE).

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)
Request Body schema: application/json
required
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Container Urn (string) or Container Urn (null) (Container Urn)
Updated At (string) or Updated At (null) (Updated At)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "container_urn": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Dataset

Update dataset by URN in path (BACKWARD COMPATIBLE).

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)
Request Body schema: application/json
required
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Container Urn (string) or Container Urn (null) (Container Urn)
Updated At (string) or Updated At (null) (Updated At)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "container_urn": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Dataset

Delete dataset by URN in path (BACKWARD COMPATIBLE).

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Dataset

Delete dataset by URN in path (BACKWARD COMPATIBLE).

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Container By Urn

Get container by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Container URN

Datasets Cursor (string) or Datasets Cursor (null) (Datasets Cursor)

Cursor for container datasets

Datasets Page Size (integer) or Datasets Page Size (null) (Datasets Page Size)

Max datasets to return for this container

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Container By Urn

Get container by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Container URN

Datasets Cursor (string) or Datasets Cursor (null) (Datasets Cursor)

Cursor for container datasets

Datasets Page Size (integer) or Datasets Page Size (null) (Datasets Page Size)

Max datasets to return for this container

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Container By Urn

Update container by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Container URN

Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Parent Urn (string) or Parent Urn (null) (Parent Urn)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "parent_urn": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Container By Urn

Update container by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Container URN

Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Parent Urn (string) or Parent Urn (null) (Parent Urn)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "parent_urn": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Container By Urn

Delete container by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Container URN

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Container By Urn

Delete container by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Container URN

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Add Dataset To Container By Urn

Add a dataset to a container by URN using query parameters.

Authorizations:
BearerAuthOAuth2Login
query Parameters
container_urn
required
string (Container Urn)

Container URN

Request Body schema: application/json
required
dataset_urn
required
string (Dataset Urn)

Responses

Request samples

Content type
application/json
{
  • "dataset_urn": "string"
}

Response samples

Content type
application/json
null

Add Dataset To Container By Urn

Add a dataset to a container by URN using query parameters.

Authorizations:
BearerAuthOAuth2Login
query Parameters
container_urn
required
string (Container Urn)

Container URN

Request Body schema: application/json
required
dataset_urn
required
string (Dataset Urn)

Responses

Request samples

Content type
application/json
{
  • "dataset_urn": "string"
}

Response samples

Content type
application/json
null

Remove Dataset From Container By Urn

Remove a dataset from a container by URN using query parameters.

Authorizations:
BearerAuthOAuth2Login
query Parameters
container_urn
required
string (Container Urn)

Container URN

dataset_urn
required
string (Dataset Urn)

Dataset URN

Responses

Response samples

Content type
application/json
null

Remove Dataset From Container By Urn

Remove a dataset from a container by URN using query parameters.

Authorizations:
BearerAuthOAuth2Login
query Parameters
container_urn
required
string (Container Urn)

Container URN

dataset_urn
required
string (Dataset Urn)

Dataset URN

Responses

Response samples

Content type
application/json
null

Get Container V2

Get container by URN using regex-based path converter (V2 - RECOMMENDED).

Example: GET /catalog/containers/v2/urn:li:container:(urn:li:dataPlatform:s3,/my/bucket/path,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
query Parameters
Datasets Cursor (string) or Datasets Cursor (null) (Datasets Cursor)

Cursor for container datasets

Datasets Page Size (integer) or Datasets Page Size (null) (Datasets Page Size)

Max datasets to return for this container

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Container V2

Get container by URN using regex-based path converter (V2 - RECOMMENDED).

Example: GET /catalog/containers/v2/urn:li:container:(urn:li:dataPlatform:s3,/my/bucket/path,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
query Parameters
Datasets Cursor (string) or Datasets Cursor (null) (Datasets Cursor)

Cursor for container datasets

Datasets Page Size (integer) or Datasets Page Size (null) (Datasets Page Size)

Max datasets to return for this container

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Container V2

Update container by URN using regex-based path converter (V2 - RECOMMENDED).

Example: PATCH /catalog/containers/v2/urn:li:container:(urn:li:dataPlatform:s3,/my/bucket/path,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Parent Urn (string) or Parent Urn (null) (Parent Urn)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "parent_urn": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Container V2

Update container by URN using regex-based path converter (V2 - RECOMMENDED).

Example: PATCH /catalog/containers/v2/urn:li:container:(urn:li:dataPlatform:s3,/my/bucket/path,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Parent Urn (string) or Parent Urn (null) (Parent Urn)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "parent_urn": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Container V2

Delete container by URN using regex-based path converter (V2 - RECOMMENDED).

Example: DELETE /catalog/containers/v2/urn:li:container:(urn:li:dataPlatform:s3,/my/bucket/path,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Container V2

Delete container by URN using regex-based path converter (V2 - RECOMMENDED).

Example: DELETE /catalog/containers/v2/urn:li:container:(urn:li:dataPlatform:s3,/my/bucket/path,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Add Dataset To Container V2

Add a dataset to a container using regex-based path converter (V2 - RECOMMENDED).

Example: POST /catalog/containers/v2/urn:li:container:(urn:li:dataPlatform:s3,/my/bucket,PROD)/datasets

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
Request Body schema: application/json
required
dataset_urn
required
string (Dataset Urn)

Responses

Request samples

Content type
application/json
{
  • "dataset_urn": "string"
}

Response samples

Content type
application/json
null

Add Dataset To Container V2

Add a dataset to a container using regex-based path converter (V2 - RECOMMENDED).

Example: POST /catalog/containers/v2/urn:li:container:(urn:li:dataPlatform:s3,/my/bucket,PROD)/datasets

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
Request Body schema: application/json
required
dataset_urn
required
string (Dataset Urn)

Responses

Request samples

Content type
application/json
{
  • "dataset_urn": "string"
}

Response samples

Content type
application/json
null

Remove Dataset From Container V2

Remove a dataset from a container using regex-based path converter (V2 - RECOMMENDED).

This endpoint properly handles both container and dataset URNs with forward slashes.

Example: DELETE /catalog/containers/v2/urn:li:container:(urn:li:dataPlatform:s3,/my/bucket,PROD)/datasets/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
null

Remove Dataset From Container V2

Remove a dataset from a container using regex-based path converter (V2 - RECOMMENDED).

This endpoint properly handles both container and dataset URNs with forward slashes.

Example: DELETE /catalog/containers/v2/urn:li:container:(urn:li:dataPlatform:s3,/my/bucket,PROD)/datasets/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
null

Add Dataset To Container

Add a dataset to a container.

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
Request Body schema: application/json
required
dataset_urn
required
string (Dataset Urn)

Responses

Request samples

Content type
application/json
{
  • "dataset_urn": "string"
}

Response samples

Content type
application/json
null

Add Dataset To Container

Add a dataset to a container.

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
Request Body schema: application/json
required
dataset_urn
required
string (Dataset Urn)

Responses

Request samples

Content type
application/json
{
  • "dataset_urn": "string"
}

Response samples

Content type
application/json
null

Remove Dataset From Container

Remove a dataset from a container.

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
null

Remove Dataset From Container

Remove a dataset from a container.

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
null

Create Container

Create a new container.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name)
Platform (string) or Platform (null) (Platform)
Description (string) or Description (null) (Description)
tags
Array of strings (Tags)
Default: []
object (Properties)
Default: {}
Parent Urn (string) or Parent Urn (null) (Parent Urn)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string"
}

Response samples

Content type
application/json
"string"

Create Container

Create a new container.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name)
Platform (string) or Platform (null) (Platform)
Description (string) or Description (null) (Description)
tags
Array of strings (Tags)
Default: []
object (Properties)
Default: {}
Parent Urn (string) or Parent Urn (null) (Parent Urn)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string"
}

Response samples

Content type
application/json
"string"

List Containers

List containers, optionally filtering by query.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Query (string) or Query (null) (Query)

Search query string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Containers

List containers, optionally filtering by query.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Query (string) or Query (null) (Query)

Search query string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Container

Get container by URN. Use :path converter for URNs with slashes.

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
query Parameters
Datasets Cursor (string) or Datasets Cursor (null) (Datasets Cursor)

Cursor for container datasets

Datasets Page Size (integer) or Datasets Page Size (null) (Datasets Page Size)

Max datasets to return for this container

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Container

Get container by URN. Use :path converter for URNs with slashes.

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
query Parameters
Datasets Cursor (string) or Datasets Cursor (null) (Datasets Cursor)

Cursor for container datasets

Datasets Page Size (integer) or Datasets Page Size (null) (Datasets Page Size)

Max datasets to return for this container

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Container

Update an existing container.

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Parent Urn (string) or Parent Urn (null) (Parent Urn)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "parent_urn": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Container

Update an existing container.

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Parent Urn (string) or Parent Urn (null) (Parent Urn)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "parent_urn": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Container

Deletes a container.

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Container

Deletes a container.

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Create Secret

Create a new secret. Owner defaults if not provided.

Authorizations:
BearerAuthOAuth2Login
query Parameters
clobber
boolean (Clobber)
Default: false

Overwrite existing secret with the same name

header Parameters
X-User-Urn (string) or X-User-Urn (null) (X-User-Urn)
Request Body schema: application/json
required
name
required
string (Name)

Unique name for the secret

value
required
string <password> (Value)

The secret value

owner
required
string (Owner)

URN of the owner (e.g., corpuser)

Description (string) or Description (null) (Description)

Optional description

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "value": "pa$$word",
  • "owner": "string",
  • "description": "string"
}

Response samples

Content type
application/json
"string"

Create Secret

Create a new secret. Owner defaults if not provided.

Authorizations:
BearerAuthOAuth2Login
query Parameters
clobber
boolean (Clobber)
Default: false

Overwrite existing secret with the same name

header Parameters
X-User-Urn (string) or X-User-Urn (null) (X-User-Urn)
Request Body schema: application/json
required
name
required
string (Name)

Unique name for the secret

value
required
string <password> (Value)

The secret value

owner
required
string (Owner)

URN of the owner (e.g., corpuser)

Description (string) or Description (null) (Description)

Optional description

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "value": "pa$$word",
  • "owner": "string",
  • "description": "string"
}

Response samples

Content type
application/json
"string"

List Secrets

Authorizations:
BearerAuthOAuth2Login
query Parameters
Query (string) or Query (null) (Query)

Search query string

header Parameters
X-User-Urn (string) or X-User-Urn (null) (X-User-Urn)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Secrets

Authorizations:
BearerAuthOAuth2Login
query Parameters
Query (string) or Query (null) (Query)

Search query string

header Parameters
X-User-Urn (string) or X-User-Urn (null) (X-User-Urn)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Secret By Urn

Get secret metadata by URN using query parameter (requires permission).

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Secret URN

header Parameters
X-User-Urn (string) or X-User-Urn (null) (X-User-Urn)

Responses

Response samples

Content type
application/json
{
  • "urn": "string",
  • "name": "string",
  • "owner": "string",
  • "description": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Secret By Urn

Get secret metadata by URN using query parameter (requires permission).

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Secret URN

header Parameters
X-User-Urn (string) or X-User-Urn (null) (X-User-Urn)

Responses

Response samples

Content type
application/json
{
  • "urn": "string",
  • "name": "string",
  • "owner": "string",
  • "description": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Secret By Urn

Delete a secret by URN using query parameter (requires permission).

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Secret URN

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Secret By Urn

Delete a secret by URN using query parameter (requires permission).

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Secret URN

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Secret

Get secret metadata by URN (requires permission).

Authorizations:
BearerAuthOAuth2Login
path Parameters
secret_urn
required
string (Secret Urn)
header Parameters
X-User-Urn (string) or X-User-Urn (null) (X-User-Urn)

Responses

Response samples

Content type
application/json
{
  • "urn": "string",
  • "name": "string",
  • "owner": "string",
  • "description": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Secret

Get secret metadata by URN (requires permission).

Authorizations:
BearerAuthOAuth2Login
path Parameters
secret_urn
required
string (Secret Urn)
header Parameters
X-User-Urn (string) or X-User-Urn (null) (X-User-Urn)

Responses

Response samples

Content type
application/json
{
  • "urn": "string",
  • "name": "string",
  • "owner": "string",
  • "description": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Secret

Delete a secret by URN (requires permission).

Authorizations:
BearerAuthOAuth2Login
path Parameters
secret_urn
required
string (Secret Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Secret

Delete a secret by URN (requires permission).

Authorizations:
BearerAuthOAuth2Login
path Parameters
secret_urn
required
string (Secret Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Secret V2

Get secret metadata by URN using regex-based path converter (V2 - RECOMMENDED).

This endpoint properly handles DataHub URNs with forward slashes.

Example: GET /catalog/secrets/v2/urn:li:secret:(urn:li:dataPlatform:file,/var/tmp/secret.key,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
secret_urn
required
string (Secret Urn)
header Parameters
X-User-Urn (string) or X-User-Urn (null) (X-User-Urn)

Responses

Response samples

Content type
application/json
{
  • "urn": "string",
  • "name": "string",
  • "owner": "string",
  • "description": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Secret V2

Get secret metadata by URN using regex-based path converter (V2 - RECOMMENDED).

This endpoint properly handles DataHub URNs with forward slashes.

Example: GET /catalog/secrets/v2/urn:li:secret:(urn:li:dataPlatform:file,/var/tmp/secret.key,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
secret_urn
required
string (Secret Urn)
header Parameters
X-User-Urn (string) or X-User-Urn (null) (X-User-Urn)

Responses

Response samples

Content type
application/json
{
  • "urn": "string",
  • "name": "string",
  • "owner": "string",
  • "description": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Secret V2

Delete a secret by URN using regex-based path converter (V2 - RECOMMENDED).

This endpoint properly handles DataHub URNs with forward slashes.

Example: DELETE /catalog/secrets/v2/urn:li:secret:(urn:li:dataPlatform:file,/var/tmp/secret.key,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
secret_urn
required
string (Secret Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Secret V2

Delete a secret by URN using regex-based path converter (V2 - RECOMMENDED).

This endpoint properly handles DataHub URNs with forward slashes.

Example: DELETE /catalog/secrets/v2/urn:li:secret:(urn:li:dataPlatform:file,/var/tmp/secret.key,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
secret_urn
required
string (Secret Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Catalog Service Root

Provides basic information about the catalog service.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
null

Catalog Service Root

Provides basic information about the catalog service.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
null

datasets

Create Dataset

Create a new dataset.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name)
platform
required
string (Platform)
environment
string (Environment)
Default: "PROD"
Description (string) or Description (null) (Description)
tags
Array of strings (Tags)
Default: []
object (Properties)
Default: {}
Schema (object) or null
Container Urn (string) or Container Urn (null) (Container Urn)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string"
}

Response samples

Content type
application/json
"string"

List Datasets

List datasets, optionally filtering by query or other properties.

When ReBAC is enabled, results are filtered to the datasets that are canonically visible to the caller under the resolved requester and workroom posture, regardless of caller origin.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Query (string) or Query (null) (Query)

Search query string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Dataset By Urn

Get dataset by URN using query parameter.

RECOMMENDED for complex URNs with forward slashes. Example: GET /catalog/datasets/by-urn?urn=urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Dataset URN

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Dataset By Urn

Update dataset by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Dataset URN

Request Body schema: application/json
required
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Container Urn (string) or Container Urn (null) (Container Urn)
Updated At (string) or Updated At (null) (Updated At)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "container_urn": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Dataset By Urn

Delete dataset by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Dataset URN

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Schema By Urn

Get schema by URN using query parameter.

RECOMMENDED for complex URNs with forward slashes. Example: GET /catalog/datasets/by-urn/schema?urn=urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Dataset URN

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "version": 0,
  • "fields": [
    ]
}

Update Schema By Urn

Update schema by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Dataset URN

Request Body schema: application/json
required
name
required
string (Name)
platform
required
string (Platform)
Version (integer) or Version (null) (Version)
required
Array of objects (Fields)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "version": 0,
  • "fields": [
    ]
}

Response samples

Content type
application/json
null

Get Dataset V2

Get dataset by URN using regex-based path converter (V2 - RECOMMENDED).

This endpoint properly handles DataHub URNs with forward slashes using custom regex matching. Supports all URN complexities while maintaining clean RESTful URLs.

Example: GET /catalog/datasets/v2/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Dataset V2

Update dataset by URN using regex-based path converter (V2 - RECOMMENDED).

Example: PATCH /catalog/datasets/v2/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)
Request Body schema: application/json
required
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Container Urn (string) or Container Urn (null) (Container Urn)
Updated At (string) or Updated At (null) (Updated At)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "container_urn": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Dataset V2

Delete dataset by URN using regex-based path converter (V2 - RECOMMENDED).

Example: DELETE /catalog/datasets/v2/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Schema V2

Get schema by URN using regex-based path converter (V2 - RECOMMENDED).

This endpoint properly handles DataHub URNs with forward slashes including sub-resources.

Example: GET /catalog/datasets/v2/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)/schema

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "version": 0,
  • "fields": [
    ]
}

Update Schema V2

Update schema by URN using regex-based path converter (V2 - RECOMMENDED).

Example: PUT /catalog/datasets/v2/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)/schema

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)
Request Body schema: application/json
required
name
required
string (Name)
platform
required
string (Platform)
Version (integer) or Version (null) (Version)
required
Array of objects (Fields)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "version": 0,
  • "fields": [
    ]
}

Response samples

Content type
application/json
null

Get Dataset

Get dataset by URN in path (BACKWARD COMPATIBLE).

NOTE: URNs with forward slashes should use /by-urn endpoint instead. For path usage, ensure proper URL encoding:

  • Single encode: %2F for /
  • May require double encoding for complex URNs: %252F

Example: GET /catalog/datasets/urn%3Ali%3Adataset%3A(urn%3Ali%3AdataPlatform%3Afile%2Csimple-name%2CPROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Dataset

Update dataset by URN in path (BACKWARD COMPATIBLE).

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)
Request Body schema: application/json
required
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Container Urn (string) or Container Urn (null) (Container Urn)
Updated At (string) or Updated At (null) (Updated At)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "container_urn": "string",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "environment": "PROD",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "dataset_schema": {
    },
  • "container_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Dataset

Delete dataset by URN in path (BACKWARD COMPATIBLE).

Authorizations:
BearerAuthOAuth2Login
path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

containers

Get Container By Urn

Get container by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Container URN

Datasets Cursor (string) or Datasets Cursor (null) (Datasets Cursor)

Cursor for container datasets

Datasets Page Size (integer) or Datasets Page Size (null) (Datasets Page Size)

Max datasets to return for this container

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Container By Urn

Update container by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Container URN

Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Parent Urn (string) or Parent Urn (null) (Parent Urn)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "parent_urn": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Container By Urn

Delete container by URN using query parameter.

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Container URN

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Add Dataset To Container By Urn

Add a dataset to a container by URN using query parameters.

Authorizations:
BearerAuthOAuth2Login
query Parameters
container_urn
required
string (Container Urn)

Container URN

Request Body schema: application/json
required
dataset_urn
required
string (Dataset Urn)

Responses

Request samples

Content type
application/json
{
  • "dataset_urn": "string"
}

Response samples

Content type
application/json
null

Remove Dataset From Container By Urn

Remove a dataset from a container by URN using query parameters.

Authorizations:
BearerAuthOAuth2Login
query Parameters
container_urn
required
string (Container Urn)

Container URN

dataset_urn
required
string (Dataset Urn)

Dataset URN

Responses

Response samples

Content type
application/json
null

Get Container V2

Get container by URN using regex-based path converter (V2 - RECOMMENDED).

Example: GET /catalog/containers/v2/urn:li:container:(urn:li:dataPlatform:s3,/my/bucket/path,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
query Parameters
Datasets Cursor (string) or Datasets Cursor (null) (Datasets Cursor)

Cursor for container datasets

Datasets Page Size (integer) or Datasets Page Size (null) (Datasets Page Size)

Max datasets to return for this container

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Container V2

Update container by URN using regex-based path converter (V2 - RECOMMENDED).

Example: PATCH /catalog/containers/v2/urn:li:container:(urn:li:dataPlatform:s3,/my/bucket/path,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Parent Urn (string) or Parent Urn (null) (Parent Urn)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "parent_urn": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Container V2

Delete container by URN using regex-based path converter (V2 - RECOMMENDED).

Example: DELETE /catalog/containers/v2/urn:li:container:(urn:li:dataPlatform:s3,/my/bucket/path,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Add Dataset To Container V2

Add a dataset to a container using regex-based path converter (V2 - RECOMMENDED).

Example: POST /catalog/containers/v2/urn:li:container:(urn:li:dataPlatform:s3,/my/bucket,PROD)/datasets

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
Request Body schema: application/json
required
dataset_urn
required
string (Dataset Urn)

Responses

Request samples

Content type
application/json
{
  • "dataset_urn": "string"
}

Response samples

Content type
application/json
null

Remove Dataset From Container V2

Remove a dataset from a container using regex-based path converter (V2 - RECOMMENDED).

This endpoint properly handles both container and dataset URNs with forward slashes.

Example: DELETE /catalog/containers/v2/urn:li:container:(urn:li:dataPlatform:s3,/my/bucket,PROD)/datasets/urn:li:dataset:(urn:li:dataPlatform:file,/var/tmp/docs,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
null

Add Dataset To Container

Add a dataset to a container.

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
Request Body schema: application/json
required
dataset_urn
required
string (Dataset Urn)

Responses

Request samples

Content type
application/json
{
  • "dataset_urn": "string"
}

Response samples

Content type
application/json
null

Remove Dataset From Container

Remove a dataset from a container.

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
null

Create Container

Create a new container.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name)
Platform (string) or Platform (null) (Platform)
Description (string) or Description (null) (Description)
tags
Array of strings (Tags)
Default: []
object (Properties)
Default: {}
Parent Urn (string) or Parent Urn (null) (Parent Urn)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string"
}

Response samples

Content type
application/json
"string"

List Containers

List containers, optionally filtering by query.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Query (string) or Query (null) (Query)

Search query string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Container

Get container by URN. Use :path converter for URNs with slashes.

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
query Parameters
Datasets Cursor (string) or Datasets Cursor (null) (Datasets Cursor)

Cursor for container datasets

Datasets Page Size (integer) or Datasets Page Size (null) (Datasets Page Size)

Max datasets to return for this container

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Container

Update an existing container.

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Properties (object) or Properties (null) (Properties)
Parent Urn (string) or Parent Urn (null) (Parent Urn)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "tags": [
    ],
  • "properties": { },
  • "parent_urn": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "platform": "string",
  • "description": "string",
  • "tags": [ ],
  • "properties": { },
  • "parent_urn": "string",
  • "urn": "string",
  • "workroom_id": "string",
  • "sub_containers": [ ],
  • "datasets": [ ],
  • "datasets_next_cursor": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Container

Deletes a container.

Authorizations:
BearerAuthOAuth2Login
path Parameters
container_urn
required
string (Container Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

secrets

Create Secret

Create a new secret. Owner defaults if not provided.

Authorizations:
BearerAuthOAuth2Login
query Parameters
clobber
boolean (Clobber)
Default: false

Overwrite existing secret with the same name

header Parameters
X-User-Urn (string) or X-User-Urn (null) (X-User-Urn)
Request Body schema: application/json
required
name
required
string (Name)

Unique name for the secret

value
required
string <password> (Value)

The secret value

owner
required
string (Owner)

URN of the owner (e.g., corpuser)

Description (string) or Description (null) (Description)

Optional description

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "value": "pa$$word",
  • "owner": "string",
  • "description": "string"
}

Response samples

Content type
application/json
"string"

List Secrets

Authorizations:
BearerAuthOAuth2Login
query Parameters
Query (string) or Query (null) (Query)

Search query string

header Parameters
X-User-Urn (string) or X-User-Urn (null) (X-User-Urn)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Secret By Urn

Get secret metadata by URN using query parameter (requires permission).

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Secret URN

header Parameters
X-User-Urn (string) or X-User-Urn (null) (X-User-Urn)

Responses

Response samples

Content type
application/json
{
  • "urn": "string",
  • "name": "string",
  • "owner": "string",
  • "description": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Secret By Urn

Delete a secret by URN using query parameter (requires permission).

Authorizations:
BearerAuthOAuth2Login
query Parameters
urn
required
string (Urn)

Secret URN

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Secret

Get secret metadata by URN (requires permission).

Authorizations:
BearerAuthOAuth2Login
path Parameters
secret_urn
required
string (Secret Urn)
header Parameters
X-User-Urn (string) or X-User-Urn (null) (X-User-Urn)

Responses

Response samples

Content type
application/json
{
  • "urn": "string",
  • "name": "string",
  • "owner": "string",
  • "description": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Secret

Delete a secret by URN (requires permission).

Authorizations:
BearerAuthOAuth2Login
path Parameters
secret_urn
required
string (Secret Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Secret V2

Get secret metadata by URN using regex-based path converter (V2 - RECOMMENDED).

This endpoint properly handles DataHub URNs with forward slashes.

Example: GET /catalog/secrets/v2/urn:li:secret:(urn:li:dataPlatform:file,/var/tmp/secret.key,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
secret_urn
required
string (Secret Urn)
header Parameters
X-User-Urn (string) or X-User-Urn (null) (X-User-Urn)

Responses

Response samples

Content type
application/json
{
  • "urn": "string",
  • "name": "string",
  • "owner": "string",
  • "description": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Secret V2

Delete a secret by URN using regex-based path converter (V2 - RECOMMENDED).

This endpoint properly handles DataHub URNs with forward slashes.

Example: DELETE /catalog/secrets/v2/urn:li:secret:(urn:li:dataPlatform:file,/var/tmp/secret.key,PROD)

Authorizations:
BearerAuthOAuth2Login
path Parameters
secret_urn
required
string (Secret Urn)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

prompts

Create Role

Create a new role.

:param role: PromptRoleCreate schema. :return: The created PromptRole model.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
tags
Array of strings (Tags)
Default: []
name
required
string (Name)
content
required
string (Content)

Responses

Request samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version": 0,
  • "created_at": "string"
}

Create Role

Create a new role.

:param role: PromptRoleCreate schema. :return: The created PromptRole model.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
tags
Array of strings (Tags)
Default: []
name
required
string (Name)
content
required
string (Content)

Responses

Request samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version": 0,
  • "created_at": "string"
}

Read Role

Retrieve a role by its ID.

:param role_id: Unique identifier of the role. :return: The requested PromptRole model. :raises HTTPException: 404 error if the role is not found.

Authorizations:
BearerAuthOAuth2Login
path Parameters
role_id
required
string <uuid> (Role Id)

Responses

Response samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version": 0,
  • "created_at": "string"
}

Read Role

Retrieve a role by its ID.

:param role_id: Unique identifier of the role. :return: The requested PromptRole model. :raises HTTPException: 404 error if the role is not found.

Authorizations:
BearerAuthOAuth2Login
path Parameters
role_id
required
string <uuid> (Role Id)

Responses

Response samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version": 0,
  • "created_at": "string"
}

Create System

Create a new system.

:param system: PromptSystemCreate schema. :return: The created PromptSystem model.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
tags
Array of strings (Tags)
Default: []
name
required
string (Name)
content
required
string (Content)

Responses

Request samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}

Create System

Create a new system.

:param system: PromptSystemCreate schema. :return: The created PromptSystem model.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
tags
Array of strings (Tags)
Default: []
name
required
string (Name)
content
required
string (Content)

Responses

Request samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}

Read System

Retrieve a system by its ID.

:param system_id: Unique identifier of the system. :return: The requested PromptSystem model. :raises HTTPException: 404 error if the system is not found.

Authorizations:
BearerAuthOAuth2Login
path Parameters
system_id
required
string <uuid> (System Id)

Responses

Response samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}

Read System

Retrieve a system by its ID.

:param system_id: Unique identifier of the system. :return: The requested PromptSystem model. :raises HTTPException: 404 error if the system is not found.

Authorizations:
BearerAuthOAuth2Login
path Parameters
system_id
required
string <uuid> (System Id)

Responses

Response samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version": 0,
  • "created_at": "2019-08-24T14:15:22Z"
}

Create Element

Create a new element.

:param element: PromptElementCreate schema. :return: The created PromptElement model.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
tags
Array of strings (Tags)
Default: []
name
required
string (Name)
content
required
string (Content)

Responses

Request samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version": 0,
  • "created_at": "string"
}

Create Element

Create a new element.

:param element: PromptElementCreate schema. :return: The created PromptElement model.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
tags
Array of strings (Tags)
Default: []
name
required
string (Name)
content
required
string (Content)

Responses

Request samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version": 0,
  • "created_at": "string"
}

Read Element

Retrieve an element by its ID.

:param element_id: Unique identifier of the element. :return: The requested PromptElement model. :raises HTTPException: 404 error if the element is not found.

Authorizations:
BearerAuthOAuth2Login
path Parameters
element_id
required
string <uuid> (Element Id)

Responses

Response samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version": 0,
  • "created_at": "string"
}

Read Element

Retrieve an element by its ID.

:param element_id: Unique identifier of the element. :return: The requested PromptElement model. :raises HTTPException: 404 error if the element is not found.

Authorizations:
BearerAuthOAuth2Login
path Parameters
element_id
required
string <uuid> (Element Id)

Responses

Response samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version": 0,
  • "created_at": "string"
}

Create Template

Create a new template.

:param template: PromptTemplateCreate schema. :return: The created PromptTemplate model.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
tags
Array of strings (Tags)
Default: []
name
required
string (Name)
content
required
string (Content)

Responses

Request samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version": 0,
  • "created_at": "string"
}

Create Template

Create a new template.

:param template: PromptTemplateCreate schema. :return: The created PromptTemplate model.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
tags
Array of strings (Tags)
Default: []
name
required
string (Name)
content
required
string (Content)

Responses

Request samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version": 0,
  • "created_at": "string"
}

Read Template

Retrieve a template by its ID.

:param template_id: Unique identifier of the template. :return: The requested PromptTemplate model. :raises HTTPException: 404 error if the template is not found.

Authorizations:
BearerAuthOAuth2Login
path Parameters
template_id
required
string <uuid> (Template Id)

Responses

Response samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version": 0,
  • "created_at": "string"
}

Read Template

Retrieve a template by its ID.

:param template_id: Unique identifier of the template. :return: The requested PromptTemplate model. :raises HTTPException: 404 error if the template is not found.

Authorizations:
BearerAuthOAuth2Login
path Parameters
template_id
required
string <uuid> (Template Id)

Responses

Response samples

Content type
application/json
{
  • "tags": [ ],
  • "name": "string",
  • "content": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "version": 0,
  • "created_at": "string"
}

embedding

Create Embedding

Create an embedding via the configured runtime embedding service.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
text
required
string (Text) <= 32768 characters

Text to generate embedding for

Model (string) or Model (null) (Model)

Model name to use

Provider Type (string) or Provider Type (null) (Provider Type)

Deprecated. Requests are always served by the runtime embedding service.

Device (string) or Device (null) (Device)

Deprecated. Requests are always served by the runtime embedding service.

Responses

Request samples

Content type
application/json
{
  • "text": "string",
  • "model": "string",
  • "provider_type": "string",
  • "device": "string"
}

Response samples

Content type
application/json
{
  • "embedding": [
    ],
  • "offset": 0
}

Create Embedding

Create an embedding via the configured runtime embedding service.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
text
required
string (Text) <= 32768 characters

Text to generate embedding for

Model (string) or Model (null) (Model)

Model name to use

Provider Type (string) or Provider Type (null) (Provider Type)

Deprecated. Requests are always served by the runtime embedding service.

Device (string) or Device (null) (Device)

Deprecated. Requests are always served by the runtime embedding service.

Responses

Request samples

Content type
application/json
{
  • "text": "string",
  • "model": "string",
  • "provider_type": "string",
  • "device": "string"
}

Response samples

Content type
application/json
{
  • "embedding": [
    ],
  • "offset": 0
}

Get Embedding Deprecated

Deprecated GET embedding endpoint.

This compatibility path includes raw text in the URL and may expose sensitive content through browser history, proxies, or access logs. Prefer POST /generate.

Authorizations:
BearerAuthOAuth2Login
path Parameters
text
required
string (Text)
query Parameters
Model (string) or Model (null) (Model)

Model name

Provider Type (string) or Provider Type (null) (Provider Type)

Deprecated. Requests are always served by the runtime embedding service.

Device (string) or Device (null) (Device)

Deprecated. Requests are always served by the runtime embedding service.

return_offset
boolean (Return Offset)
Default: false

Responses

Response samples

Content type
application/json
{
  • "embedding": [
    ],
  • "offset": 0
}

Get Embedding Deprecated

Deprecated GET embedding endpoint.

This compatibility path includes raw text in the URL and may expose sensitive content through browser history, proxies, or access logs. Prefer POST /generate.

Authorizations:
BearerAuthOAuth2Login
path Parameters
text
required
string (Text)
query Parameters
Model (string) or Model (null) (Model)

Model name

Provider Type (string) or Provider Type (null) (Provider Type)

Deprecated. Requests are always served by the runtime embedding service.

Device (string) or Device (null) (Device)

Deprecated. Requests are always served by the runtime embedding service.

return_offset
boolean (Return Offset)
Default: false

Responses

Response samples

Content type
application/json
{
  • "embedding": [
    ],
  • "offset": 0
}

Chunk Text

Chunk text via the configured runtime embedding service.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Model (string) or Model (null) (Model)

Model name to use

Provider Type (string) or Provider Type (null) (Provider Type)

Deprecated. Requests are always served by the runtime embedding service.

Device (string) or Device (null) (Device)

Deprecated. Requests are always served by the runtime embedding service.

Request Body schema: application/json
required
text
required
string (Text) non-empty

Text to be chunked

max_length
integer (Max Length) [ 50 .. 8192 ]
Default: 510

Maximum length of each chunk

overlap
integer (Overlap) >= 0
Default: 32

Number of tokens to overlap between chunks

preamble_text
string (Preamble Text) <= 10000 characters
Default: ""

Text to prepend to each chunk

return_metadata
boolean (Return Metadata)
Default: false

Whether to return metadata with chunks

Responses

Request samples

Content type
application/json
{
  • "text": "string",
  • "max_length": 510,
  • "overlap": 32,
  • "preamble_text": "",
  • "return_metadata": false
}

Response samples

Content type
application/json
Example
[ ]

Chunk Text

Chunk text via the configured runtime embedding service.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Model (string) or Model (null) (Model)

Model name to use

Provider Type (string) or Provider Type (null) (Provider Type)

Deprecated. Requests are always served by the runtime embedding service.

Device (string) or Device (null) (Device)

Deprecated. Requests are always served by the runtime embedding service.

Request Body schema: application/json
required
text
required
string (Text) non-empty

Text to be chunked

max_length
integer (Max Length) [ 50 .. 8192 ]
Default: 510

Maximum length of each chunk

overlap
integer (Overlap) >= 0
Default: 32

Number of tokens to overlap between chunks

preamble_text
string (Preamble Text) <= 10000 characters
Default: ""

Text to prepend to each chunk

return_metadata
boolean (Return Metadata)
Default: false

Whether to return metadata with chunks

Responses

Request samples

Content type
application/json
{
  • "text": "string",
  • "max_length": 510,
  • "overlap": 32,
  • "preamble_text": "",
  • "return_metadata": false
}

Response samples

Content type
application/json
Example
[ ]

Embed Chunks

Embed chunks via the configured runtime embedding service.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Model (string) or Model (null) (Model)

Model name to use

Provider Type (string) or Provider Type (null) (Provider Type)

Deprecated. Requests are always served by the runtime embedding service.

Device (string) or Device (null) (Device)

Deprecated. Requests are always served by the runtime embedding service.

batch_size
integer (Batch Size)
Default: 64

Deprecated. This value is ignored; batching is controlled by the runtime embedding service.

Request Body schema: application/json
required
Array (<= 256 items)
string <= 32768 characters

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • [
    ]
]

Embed Chunks

Embed chunks via the configured runtime embedding service.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Model (string) or Model (null) (Model)

Model name to use

Provider Type (string) or Provider Type (null) (Provider Type)

Deprecated. Requests are always served by the runtime embedding service.

Device (string) or Device (null) (Device)

Deprecated. Requests are always served by the runtime embedding service.

batch_size
integer (Batch Size)
Default: 64

Deprecated. This value is ignored; batching is controlled by the runtime embedding service.

Request Body schema: application/json
required
Array (<= 256 items)
string <= 32768 characters

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • [
    ]
]

Get Providers

Return the embedding provider surface exposed by core.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get Providers

Return the embedding provider surface exposed by core.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
[
  • "string"
]

Health Check

Health check for embedding service.

Unauthenticated — used as K8s liveness/readiness probe in standalone embedding deployments (Metal GPU chart).

Responses

Response samples

Content type
application/json
null

Health Check

Health check for embedding service.

Unauthenticated — used as K8s liveness/readiness probe in standalone embedding deployments (Metal GPU chart).

Responses

Response samples

Content type
application/json
null

cluster

Create Location

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name)

Name of the location

Datacenter (string) or Datacenter (null) (Datacenter)

Datacenter of the location

Region (string) or Region (null) (Region)

Region of the location

Zone (string) or Zone (null) (Zone)

Zone of the location

Building (string) or Building (null) (Building)

Building of the location

Address (string) or Address (null) (Address)

Address of the location

Contact Phone (string) or Contact Phone (null) (Contact Phone)

Contact phone for the location

Contact Name (string) or Contact Name (null) (Contact Name)

Contact name for the location

Contact Email (string) or Contact Email (null) (Contact Email)

Contact email for the location

Placement Group Id (string) or Placement Group Id (null) (Placement Group Id)

Ray placement group ID

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "datacenter": "string",
  • "region": "string",
  • "zone": "string",
  • "building": "string",
  • "address": "string",
  • "contact_phone": "string",
  • "contact_name": "string",
  • "contact_email": "user@example.com",
  • "placement_group_id": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "datacenter": "string",
  • "region": "string",
  • "zone": "string",
  • "building": "string",
  • "address": "string",
  • "contact_phone": "string",
  • "contact_name": "string",
  • "contact_email": "user@example.com",
  • "placement_group_id": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z"
}

Update Location

Update an existing location by its ID.

Args: location_id (UUID): The unique identifier of the location to update. location (CreateLocation): The new data for the location.

Returns: Location: The updated location object.

Authorizations:
BearerAuthOAuth2Login
path Parameters
location_id
required
string <uuid> (Location Id)
Request Body schema: application/json
required
name
required
string (Name)

Name of the location

Datacenter (string) or Datacenter (null) (Datacenter)

Datacenter of the location

Region (string) or Region (null) (Region)

Region of the location

Zone (string) or Zone (null) (Zone)

Zone of the location

Building (string) or Building (null) (Building)

Building of the location

Address (string) or Address (null) (Address)

Address of the location

Contact Phone (string) or Contact Phone (null) (Contact Phone)

Contact phone for the location

Contact Name (string) or Contact Name (null) (Contact Name)

Contact name for the location

Contact Email (string) or Contact Email (null) (Contact Email)

Contact email for the location

Placement Group Id (string) or Placement Group Id (null) (Placement Group Id)

Ray placement group ID

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "datacenter": "string",
  • "region": "string",
  • "zone": "string",
  • "building": "string",
  • "address": "string",
  • "contact_phone": "string",
  • "contact_name": "string",
  • "contact_email": "user@example.com",
  • "placement_group_id": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "datacenter": "string",
  • "region": "string",
  • "zone": "string",
  • "building": "string",
  • "address": "string",
  • "contact_phone": "string",
  • "contact_name": "string",
  • "contact_email": "user@example.com",
  • "placement_group_id": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z"
}

Get Location

Authorizations:
BearerAuthOAuth2Login
path Parameters
location_id
required
string <uuid> (Location Id)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "datacenter": "string",
  • "region": "string",
  • "zone": "string",
  • "building": "string",
  • "address": "string",
  • "contact_phone": "string",
  • "contact_name": "string",
  • "contact_email": "user@example.com",
  • "placement_group_id": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z"
}

List Locations

Authorizations:
BearerAuthOAuth2Login
query Parameters
Skip (integer) or Skip (null) (Skip)
Limit (integer) or Limit (null) (Limit)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Cluster

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
location_id
required
string <uuid> (Location Id)

Unique identifier for the location of the cluster

name
required
string (Name)

Name of the cluster

Responses

Request samples

Content type
application/json
{
  • "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
  • "name": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "location_name": "string"
}

Get Cluster

Authorizations:
BearerAuthOAuth2Login
path Parameters
cluster_id
required
string <uuid> (Cluster Id)

Responses

Response samples

Content type
application/json
{
  • "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
  • "name": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "location_name": "string"
}

List Clusters

Authorizations:
BearerAuthOAuth2Login
query Parameters
Skip (integer) or Skip (null) (Skip)
Limit (integer) or Limit (null) (Limit)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Node By Id

Authorizations:
BearerAuthOAuth2Login
path Parameters
required
Node Id (string) or Node Id (string) (Node Id)

Responses

Response samples

Content type
application/json
{
  • "node": {
    },
  • "location": {
    },
  • "hardware": {
    },
  • "node_list_node": {
    }
}

Get Running Nodes

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Nodes

Authorizations:
BearerAuthOAuth2Login
query Parameters
Skip (integer) or Skip (null) (Skip)
Limit (integer) or Limit (null) (Limit)
Active (boolean) or Active (null) (Active)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Hardware

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
Name (string) or Name (null) (Name)

Name of the hardware

Array of Gpus (objects) or Gpus (null) (Gpus)

GPU configuration of the hardware

Cluster Ip (string) or Cluster Ip (null) (Cluster Ip)

Cluster IP of the hardware

Array of Processors (strings) or Processors (null) (Processors)

Processor configuration of the hardware

Processor Vendor (string) or Processor Vendor (null) (Processor Vendor)

Processor vendor of the hardware

Os (string) or Os (null) (Os)

Operating system of the hardware

Platform (string) or Platform (null) (Platform)

Platform of the hardware

Local Node Id (string) or Local Node Id (null) (Local Node Id)

Local node ID of the hardware

Ray Node Id (string) or Ray Node Id (null) (Ray Node Id)

Ray node ID of the hardware

Configuration (object) or Configuration (null) (Configuration)

Configuration of the hardware

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "gpus": [
    ],
  • "cluster_ip": "string",
  • "processors": [
    ],
  • "processor_vendor": "string",
  • "os": "string",
  • "platform": "string",
  • "local_node_id": "string",
  • "ray_node_id": "string",
  • "configuration": { }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "gpus": [
    ],
  • "cluster_ip": "string",
  • "processors": [
    ],
  • "processor_vendor": "string",
  • "os": "string",
  • "platform": "string",
  • "local_node_id": "string",
  • "ray_node_id": "string",
  • "configuration": { },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "node_id": "6e0bdcac-9717-4a6f-972e-97489dffeb0c",
  • "active": true
}

List Hardware

Authorizations:
BearerAuthOAuth2Login
query Parameters
Skip (integer) or Skip (null) (Skip)
Limit (integer) or Limit (null) (Limit)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Hardware

Authorizations:
BearerAuthOAuth2Login
path Parameters
hardware_id
required
string <uuid> (Hardware Id)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "gpus": [
    ],
  • "cluster_ip": "string",
  • "processors": [
    ],
  • "processor_vendor": "string",
  • "os": "string",
  • "platform": "string",
  • "local_node_id": "string",
  • "ray_node_id": "string",
  • "configuration": { },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "node_id": "6e0bdcac-9717-4a6f-972e-97489dffeb0c",
  • "active": true
}

Get Runtime Config

Endpoint to retrieve the runtime configuration of the cluster.

Returns: Dict[str, Any]: A dictionary containing the runtime configuration settings.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{ }

Get Cluster Capabilities

Endpoint to retrieve cluster capabilities for model deployment and platform selection.

Returns hardware information, system type, available platforms, and tool availability including whether llamacpp is installed and what inference engines are supported.

Auth widened by ENG-4697 / T5.20: viewer or owner on cluster: (admin's install-seeded owner relation still passes). NB pairing does NOT seed a cluster-viewer grant (ENG-7892): a mesh-origin peer must be granted cluster: viewer explicitly to probe, else 403.

Returns: Dict[str, Any]: A dictionary containing cluster capabilities information.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{ }

Attach Pairing

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
remote_host
required
string (Remote Host)

Hostname or IP of the paired GPU node

Remote User (string) or Remote User (null) (Remote User)

SSH username for the paired node

Ssh Key Path (string) or Ssh Key Path (null) (Ssh Key Path)

Path to the SSH private key on the head node

Models Root (string) or Models Root (null) (Models Root)

Model storage root on the paired node

Strict Host Key Checking (boolean) or Strict Host Key Checking (null) (Strict Host Key Checking)
Default: false

Enforce strict SSH host key checking

Additional Env (object) or Additional Env (null) (Additional Env)

Additional environment variables to set before remote commands

Responses

Request samples

Content type
application/json
{
  • "remote_host": "string",
  • "remote_user": "string",
  • "ssh_key_path": "string",
  • "models_root": "string",
  • "strict_host_key_checking": false,
  • "additional_env": {
    }
}

Response samples

Content type
application/json
null

Detach Pairing

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
null

Refresh Hardware

Manually refresh hardware information by re-detecting and storing it. This will update the database with the latest hardware detection results.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
null

Cluster Get Hostname

Endpoint to provide the hostname to be tested by the client.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
null

Create Federation

Create a new cluster federation.

Args: federation: Federation creation data

Returns: Created ClusterFederation object

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
remote_cluster_name
required
string (Remote Cluster Name)

Name of the remote cluster for display

Array of objects (Remote Ips)

List of remote endpoints. Each entry: {'ip': , 'primary': bool, 'hostname': }. ENG-7427: when 'hostname' is set the platform connects to 'ip' but sends Host + TLS SNI = hostname (so the istio gateway routes by FQDN); without it, routing falls back to 'ip' (direct-IP deployments). Required for initiator, optional for receiver.

preshared_key
required
string (Preshared Key)

Pre-shared key for authentication. Required — both clusters must use the same PSK.

Callback Hostname (string) or Callback Hostname (null) (Callback Hostname)

Optional hostname/IP for remote cluster to use for callbacks

role
string (Role)
Default: "initiator"
Enum: "initiator" "receiver"

Federation role: 'initiator' or 'receiver'. Receiver creates a WAITING record.

Local Kc Issuer Url (string) or Local Kc Issuer Url (null) (Local Kc Issuer Url)

Optional Keycloak realm issuer URL for THIS cluster's brokering identity (e.g. https://host/realms/kamiwaza). When set, overrides the cluster's own auth issuer (AUTH_GATEWAY_JWT_ISSUER) for this pair.

Local Kc Jwks Url (string) or Local Kc Jwks Url (null) (Local Kc Jwks Url)

Optional Keycloak JWKS URL for THIS cluster's brokering identity. When set, overrides the issuer-derived brokering JWKS URL for this pair.

Local Broker Client Id (string) or Local Broker Client Id (null) (Local Broker Client Id)

Optional Keycloak client ID THIS cluster uses for token-exchange brokering. When set, overrides KAMIWAZA_KC_BROKER_CLIENT_ID env at pair time.

Local Broker Client Secret (string) or Local Broker Client Secret (null) (Local Broker Client Secret)

DataHub secret URN (e.g. urn:li:dataHubSecret:...) for the Keycloak broker client secret. URN-only at this API ingress — raw secrets are refused so the operator's payload never lands in API request logs or the local override DB row in plaintext. Operators store the raw secret in DataHub first (via the secrets API) and supply the URN here. Wire-level disposition: at pair time the server resolves the URN via CatalogService and ships the raw secret to the peer's KC over the federation pair channel. That channel is HTTPS (AUTH_GATEWAY_TLS_INSECURE is an explicit dev escape hatch) and the body is PSK-HMAC-signed (cluster_trust.sign_federation_request) — same wire posture as the pre-existing env-driven path (KAMIWAZA_KC_BROKER_CLIENT_SECRET). The URN-only claim applies to API ingress + local override storage, not to the receiver's peer_broker_client_secret_urn DB row (which despite its name has always stored the raw value in the env-driven path — see column comment in models/cluster.py).

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "remote_cluster_name": "string",
  • "remote_ips": [
    ],
  • "callback_hostname": "string",
  • "local_cluster_id": "1260b091-d4ae-49be-a02b-b44ea252bd7e",
  • "remote_cluster_id": "2e5a86d7-242f-4a38-9dcb-3cd98ca8c46e",
  • "status": "string",
  • "last_activity": "2019-08-24T14:15:22Z",
  • "last_ping": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "peer_kc_issuer_url": "string",
  • "peer_kc_jwks_url": "string",
  • "peer_broker_client_id": "string",
  • "peer_broker_client_secret_urn": "string",
  • "brokering_enabled": true
}

List Federations

List all cluster federations with optional filtering.

Args: skip: Number of records to skip limit: Maximum number of records to return status: Filter by status (PAIRING|PAIRED|DISCONNECTED|DELETED)

Returns: List of ClusterFederation objects

Authorizations:
BearerAuthOAuth2Login
query Parameters
Skip (integer) or Skip (null) (Skip)
Default: 0
Limit (integer) or Limit (null) (Limit)
Default: 100
Status (string) or Status (null) (Status)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Federation

Get a single cluster federation by ID.

Args: federation_id: UUID of the federation

Returns: ClusterFederation object

Authorizations:
BearerAuthOAuth2Login
path Parameters
federation_id
required
string <uuid> (Federation Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "remote_cluster_name": "string",
  • "remote_ips": [
    ],
  • "callback_hostname": "string",
  • "local_cluster_id": "1260b091-d4ae-49be-a02b-b44ea252bd7e",
  • "remote_cluster_id": "2e5a86d7-242f-4a38-9dcb-3cd98ca8c46e",
  • "status": "string",
  • "last_activity": "2019-08-24T14:15:22Z",
  • "last_ping": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "peer_kc_issuer_url": "string",
  • "peer_kc_jwks_url": "string",
  • "peer_broker_client_id": "string",
  • "peer_broker_client_secret_urn": "string",
  • "brokering_enabled": true
}

Update Federation

Update a cluster federation.

Args: federation_id: UUID of the federation updates: Dictionary of fields to update

Returns: Updated ClusterFederation object

Authorizations:
BearerAuthOAuth2Login
path Parameters
federation_id
required
string <uuid> (Federation Id)
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "remote_cluster_name": "string",
  • "remote_ips": [
    ],
  • "callback_hostname": "string",
  • "local_cluster_id": "1260b091-d4ae-49be-a02b-b44ea252bd7e",
  • "remote_cluster_id": "2e5a86d7-242f-4a38-9dcb-3cd98ca8c46e",
  • "status": "string",
  • "last_activity": "2019-08-24T14:15:22Z",
  • "last_ping": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "peer_kc_issuer_url": "string",
  • "peer_kc_jwks_url": "string",
  • "peer_broker_client_id": "string",
  • "peer_broker_client_secret_urn": "string",
  • "brokering_enabled": true
}

Delete Federation

Soft delete a cluster federation (mark as DELETED).

Args: federation_id: UUID of the federation

Returns: Success message

Authorizations:
BearerAuthOAuth2Login
path Parameters
federation_id
required
string <uuid> (Federation Id)

Responses

Response samples

Content type
application/json
null

Add Federation User

Add a brokered user to a federation's allowlist (FR-51 / FR-80).

Authorizations:
BearerAuthOAuth2Login
path Parameters
federation_id
required
string <uuid> (Federation Id)
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
null

List Federation Users

List all brokered users on a federation's allowlist.

Carries NativeRealmRequired (ENG-7890): the allowlist (external IDs, initial tuples) is cross-relationship data a mesh-origin peer admin must not be able to enumerate for an arbitrary federation_id.

Authorizations:
BearerAuthOAuth2Login
path Parameters
federation_id
required
string <uuid> (Federation Id)

Responses

Response samples

Content type
application/json
null

Revoke Federation User

Revoke a brokered user (FR-79).

Sets disabled_at = now() on the allowlist row — next inbound mesh request from the user is rejected at brokered_ingress with revoked_brokered_user.

When cancel_in_flight_jobs=true (ENG-4708 / T5.31), also marks the user's active jobs as STOPPED in the DB so the in-flight compute reports as canceled in GET /api/cluster/jobs. The cascade is best-effort: failures log but do not roll back the revoke itself — the gate (disabled_at) is the load-bearing guarantee.

Authorizations:
BearerAuthOAuth2Login
path Parameters
federation_id
required
string <uuid> (Federation Id)
external_id
required
string (External Id)
query Parameters
cancel_in_flight_jobs
boolean (Cancel In Flight Jobs)
Default: false

Responses

Response samples

Content type
application/json
null

Pair Federation

Initiate the pairing process for a federation.

Args: federation_id: UUID of the federation to pair

Returns: Updated ClusterFederation object

Authorizations:
BearerAuthOAuth2Login
path Parameters
federation_id
required
string <uuid> (Federation Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "remote_cluster_name": "string",
  • "remote_ips": [
    ],
  • "callback_hostname": "string",
  • "local_cluster_id": "1260b091-d4ae-49be-a02b-b44ea252bd7e",
  • "remote_cluster_id": "2e5a86d7-242f-4a38-9dcb-3cd98ca8c46e",
  • "status": "string",
  • "last_activity": "2019-08-24T14:15:22Z",
  • "last_ping": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "peer_kc_issuer_url": "string",
  • "peer_kc_jwks_url": "string",
  • "peer_broker_client_id": "string",
  • "peer_broker_client_secret_urn": "string",
  • "brokering_enabled": true
}

Disconnect Federation

Disconnect a federation gracefully or forcefully.

Args: federation_id: UUID of the federation to disconnect force: If True, disconnect without waiting for acknowledgment

Returns: Success message

Authorizations:
BearerAuthOAuth2Login
path Parameters
federation_id
required
string <uuid> (Federation Id)
query Parameters
force
boolean (Force)
Default: false

Responses

Response samples

Content type
application/json
null

Ping Federation

Health check a federated cluster.

Carries NativeRealmRequired (ENG-7890): ping triggers an outbound action against a peer, so a mesh-origin caller must not be able to invoke it.

Args: federation_id: UUID of the federation to ping

Returns: Ping status

Authorizations:
BearerAuthOAuth2Login
path Parameters
federation_id
required
string <uuid> (Federation Id)

Responses

Response samples

Content type
application/json
null

cluster-remote

Handle Pair Federation

Handle incoming federation pairing request from remote cluster.

Requires a valid HMAC signature matching a WAITING federation record.

Authorizations:
OAuth2LoginBearerAuth
Request Body schema: application/json
required
required
Local Cluster Id (string) or Local Cluster Id (string) (Local Cluster Id)

ID of the requesting cluster

local_cluster_name
required
string (Local Cluster Name)

Name of the requesting cluster

required
Array of objects (Local Ips)

List of local IPs with primary flag

Admin User Id (string) or Admin User Id (null) (Admin User Id)

Admin user who initiated pairing (for ReBAC seeding on target)

Local Ca Cert (string) or Local Ca Cert (null) (Local Ca Cert)

PEM-encoded root CA certificate for TLS verification of this cluster

Peer Kc Issuer Url (string) or Peer Kc Issuer Url (null) (Peer Kc Issuer Url)

Peer Keycloak realm issuer URL (e.g. https://host/realms/kamiwaza)

Peer Kc Jwks Url (string) or Peer Kc Jwks Url (null) (Peer Kc Jwks Url)

Peer Keycloak JWKs URL for IdP signature verification

Peer Broker Client Id (string) or Peer Broker Client Id (null) (Peer Broker Client Id)

Peer-side client_id pre-provisioned at install for cross-realm brokering

Peer Broker Client Secret (string) or Peer Broker Client Secret (null) (Peer Broker Client Secret)

Peer-side client_secret matching peer_broker_client_id

Responses

Request samples

Content type
application/json
{
  • "local_cluster_id": "1260b091-d4ae-49be-a02b-b44ea252bd7e",
  • "local_cluster_name": "string",
  • "local_ips": [
    ],
  • "admin_user_id": "string",
  • "local_ca_cert": "string",
  • "peer_kc_issuer_url": "string",
  • "peer_kc_jwks_url": "string",
  • "peer_broker_client_id": "string",
  • "peer_broker_client_secret": "string"
}

Response samples

Content type
application/json
null

Handle Remote Ping

Handle incoming ping from a federated cluster.

Requires a valid HMAC signature from the paired cluster. Returns the local cluster ID to confirm liveness.

Authorizations:
OAuth2LoginBearerAuth

Responses

Response samples

Content type
application/json
null

Handle Disconnect Request

Handle incoming disconnect request from remote cluster.

Requires a valid HMAC signature from the paired cluster.

Authorizations:
OAuth2LoginBearerAuth
Request Body schema: application/json
required
required
Federation Id (string) or Federation Id (string) (Federation Id)

Federation ID to disconnect

required
Cluster Id (string) or Cluster Id (string) (Cluster Id)

Cluster ID requesting disconnect

Reason (string) or Reason (null) (Reason)

Reason for disconnection

Responses

Request samples

Content type
application/json
{
  • "federation_id": "ace943d5-f456-4364-a519-e1de625df434",
  • "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616",
  • "reason": "string"
}

Response samples

Content type
application/json
null

cluster-jobs

Submit Job

Submit a Ray job asynchronously. Returns immediately with job ID.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
entrypoint
required
string (Entrypoint) non-empty

Shell command to execute (e.g. 'python script.py')

Runtime Env (object) or Runtime Env (null) (Runtime Env)

Ray runtime_env dict. Only the env_vars key is honored; execution-environment keys (pip, working_dir, py_modules, conda) are stripped server-side as a supply-chain safeguard (ENG-3782).

Timeout Seconds (integer) or Timeout Seconds (null) (Timeout Seconds)

Max seconds before auto-cancel (1–86400).

Metadata (object) or Metadata (null) (Metadata)

Arbitrary key-value metadata attached to the job record.

Responses

Request samples

Content type
application/json
{
  • "entrypoint": "string",
  • "runtime_env": { },
  • "timeout_seconds": 86400,
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "ray_job_id": "string",
  • "status": "PENDING"
}

Run Job

Submit a Ray job and block until it completes or times out.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
entrypoint
required
string (Entrypoint) non-empty

Shell command to execute (e.g. 'python script.py')

Runtime Env (object) or Runtime Env (null) (Runtime Env)

Ray runtime_env dict. Only the env_vars key is honored; execution-environment keys (pip, working_dir, py_modules, conda) are stripped server-side as a supply-chain safeguard (ENG-3782).

Timeout Seconds (integer) or Timeout Seconds (null) (Timeout Seconds)

Max seconds before auto-cancel (1–86400).

Metadata (object) or Metadata (null) (Metadata)

Arbitrary key-value metadata attached to the job record.

Responses

Request samples

Content type
application/json
{
  • "entrypoint": "string",
  • "runtime_env": { },
  • "timeout_seconds": 86400,
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "ray_job_id": "string",
  • "status": "PENDING",
  • "result": { },
  • "error_type": "string",
  • "error_message": "string",
  • "duration_seconds": 0,
  • "timed_out": false
}

List Jobs

List jobs the caller can see (T5.29 / ENG-4706).

Newest-first; limit + offset pagination. Mesh callers see only jobs from their own source cluster — the source_filter matches the per-job isolation property from get_status.

Demo bullet (2): kz.cluster.operations() builds on this.

Authorizations:
BearerAuthOAuth2Login
query Parameters
limit
integer (Limit) [ 1 .. 100 ]
Default: 100
offset
integer (Offset) [ 0 .. 10000 ]
Default: 0

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Job Status

Get current status of a submitted job.

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ray_job_id": "string",
  • "status": "PENDING",
  • "source": "string",
  • "source_cluster_id": "string",
  • "source_cluster_name": "string",
  • "user_id": "string",
  • "entrypoint": "string",
  • "runtime_env": { },
  • "metadata_": { },
  • "timeout_seconds": 0,
  • "timed_out": false,
  • "error_type": "string",
  • "error_message": "string",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "ended_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Job Result

Extract the structured JSON result from a succeeded job's logs.

ENG-6699 — passes the caller's gate attributes (X-User-Attributes, set by ext-authz) so gated target datasets are record-filtered before the result is released.

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)

Responses

Response samples

Content type
application/json
null

Get Job Logs

Return stdout/stderr logs for a job.

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)

Responses

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "logs": "string"
}

Cancel Job

Cancel a running job.

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "ray_job_id": "string",
  • "status": "PENDING",
  • "source": "string",
  • "source_cluster_id": "string",
  • "source_cluster_name": "string",
  • "user_id": "string",
  • "entrypoint": "string",
  • "runtime_env": { },
  • "metadata_": { },
  • "timeout_seconds": 0,
  • "timed_out": false,
  • "error_type": "string",
  • "error_message": "string",
  • "submitted_at": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "ended_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

cluster-diagnose

Diagnose

Run cluster health probes and return a structured ClusterDiagnostics.

Admin-only per §4.2.10 auth table. Probes are fail-soft individually, but a top-level orchestration failure is surfaced as 500 so operators notice a broken diagnose pipeline.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "cluster_id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "issues": [ ],
  • "has_issues": false
}

authz-gates

Discover Gate

Reflect on a Gate classpath and return its metadata.

Per design §4.2.3:

  • 404 classpath_unimportable when the module/class can't be loaded (ImportError, AttributeError, ValueError on bad shape).
  • 400 not_a_gate when the loaded class isn't an AttributeGate or ExecutionGate subclass.
  • 400 gate_not_constructible when the class can't be zero-arg instantiated (ENG-4870).
  • 403 classpath_not_allowed when the classpath is outside the configured prefix allowlist (ENG-4861).

Auth (ENG-4861): native-realm only (mesh-origin requests blocked by require_native_realm_dep) + ReBAC viewer/owner on the local cluster. Native-realm enforcement prevents brokered mesh viewers from triggering importlib.import_module side effects on the receiver; the cluster-viewer check then layers ReBAC on top.

No state mutation; safe to call repeatedly. Successful responses are memoized in _DISCOVER_CACHE for the process lifetime (v0.3.5 OQ-10) — invalidated by _clear_discover_cache() from the cluster-binding API (T2.4) or a future gate-package install/replace flow (M5). Failure responses (404 / 400 / 403) are never cached so an operator who fixes a typo or installs the missing extension can retry without a pod restart.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
classpath
required
string (Classpath)

Responses

Request samples

Content type
application/json
{
  • "classpath": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "kind": "string",
  • "required_attributes": [
    ],
  • "config_schema": { },
  • "classpath": "string",
  • "location": "string"
}

cluster-gate-binding

Get Execution Gate

T2.4: read the active ExecutionGate binding for this cluster.

Returns 404 not_configured when no binding is persisted — the JobGateRunner default (ALLOW local, DENY mesh) is the operating posture in that case.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "type": "string",
  • "config": { },
  • "gate_name": "string",
  • "kind": "string"
}

Set Execution Gate

T2.4: bind an ExecutionGate to this cluster.

Auth (M3 Proactive Security Checklist §4.4.3.1):

  • NativeRealmRequired: mesh-origin requests rejected.
  • AdminUser: cluster-wide execution gate replacement is an admin mutation (parallel to kamiwaza/cluster/api.py mutators). Any authenticated non-admin would otherwise be able to flip the authz outcome for every job submission on the cluster.

Side effects:

  • Validates type is an ExecutionGate subclass (else 400 wrong_kind).
  • Validates config against gate.config_schema() (T2.6).
  • Writes runtime_config[authz.execution_gate] = {type, config}.
  • Invalidates the discover cache so the next reflect() call observes the now-active gate (v0.3.5 OQ-10).
Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
type
required
string (Type)
object (Config)
Default: {}

Responses

Request samples

Content type
application/json
{
  • "type": "string",
  • "config": { }
}

Response samples

Content type
application/json
{
  • "type": "string",
  • "config": { },
  • "gate_name": "string",
  • "kind": "string"
}

Delete Execution Gate

T2.4: clear the cluster's ExecutionGate binding.

Returns 404 not_configured when there is nothing to clear so the caller can distinguish "deleted X" from "nothing was there".

Auth (M3 Proactive Security Checklist §4.4.3.1):

  • NativeRealmRequired: mesh-origin requests rejected.
  • AdminUser: clearing the cluster execution gate is a mutation of cluster-wide authz state. Same justification as the PUT above.
Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{ }

authz-subjects

Upsert Subject

T3.5: idempotent upsert at PUT /api/authz/subjects/{id_or_username}.

Auth (M3 Proactive Security Checklist §4.4.3.1):

  • AdminUser: Keycloak admin role required (subject management is an admin function — subjects ARE the principals ReBAC names, so ReBAC ownership doesn't recurse here).
  • NativeRealmRequired: mesh-origin rejected. Brokered mesh viewers must not provision subjects on the receiver.
Authorizations:
BearerAuthOAuth2Login
path Parameters
id_or_username
required
string (Id Or Username)
Request Body schema: application/json
required
required
object (Attributes)
Password (string) or Password (null) (Password)

Responses

Request samples

Content type
application/json
{
  • "attributes": { },
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "username": "string",
  • "attributes": { },
  • "grants": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Subject

T3.5: read the Subject by KC UUID or username.

Auth: AdminUser (admin-only in M3). Self-read (a non-admin reading their own subject) is a separate use case — wires in M3.1+ when an end-user surface needs it; the M3 demo author runs setup.py as admin and never hits self-read.

Authorizations:
BearerAuthOAuth2Login
path Parameters
id_or_username
required
string (Id Or Username)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "username": "string",
  • "attributes": { },
  • "grants": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Subject

T3.5: delete the Subject by KC UUID or username.

Auth: AdminUser + NativeRealmRequired.

?cascade=grants forwards cascade_grants=True to the service so the subject's ReBAC tuples are removed BEFORE the KC user delete fires (ENG-4937). Any other cascade value is rejected to keep the API surface tight.

Authorizations:
BearerAuthOAuth2Login
path Parameters
id_or_username
required
string (Id Or Username)
query Parameters
Cascade (string) or Cascade (null) (Cascade)

Set to grants to cascade-remove the subject's ReBAC relations (ENG-4937). Omit to keep grants in place.

Responses

Response samples

Content type
application/json
{ }

Create Grant

T3.6: bind a ReBAC tuple (subject, object, relation).

Subject namespace is fixed at user (corpuser equivalent); the caller-supplied object_namespace / object_id / relation name the target side and the verb. Delegates to relationship_store.

Authorizations:
BearerAuthOAuth2Login
path Parameters
id_or_username
required
string (Id Or Username)
Request Body schema: application/json
required
object_namespace
required
string (Object Namespace)
object_id
required
string (Object Id)
relation
required
string (Relation)

Responses

Request samples

Content type
application/json
{
  • "object_namespace": "string",
  • "object_id": "string",
  • "relation": "string"
}

Response samples

Content type
application/json
{
  • "object_namespace": "string",
  • "object_id": "string",
  • "relation": "string"
}

List Grants

T3.6: list all ReBAC tuples bound to this subject.

Authorizations:
BearerAuthOAuth2Login
path Parameters
id_or_username
required
string (Id Or Username)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Grant

T3.6: remove a ReBAC tuple (subject, object, relation).

Tuple-key body (not path) because relation values can contain characters that don't path-encode cleanly. Same shape as POST.

Authorizations:
BearerAuthOAuth2Login
path Parameters
id_or_username
required
string (Id Or Username)
Request Body schema: application/json
required
object_namespace
required
string (Object Namespace)
object_id
required
string (Object Id)
relation
required
string (Relation)

Responses

Request samples

Content type
application/json
{
  • "object_namespace": "string",
  • "object_id": "string",
  • "relation": "string"
}

Response samples

Content type
application/json
{ }

authz-gate-packages

List Gate Packages

List installed gate packages (FR-90 / FR-95).

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "per_page": 20
}

Install Gate Package

Install a gate package (FR-89 / FR-95).

Hash-pin is mandatory. The pip subprocess runs with --require-hashes against the chart-configured index URL.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
package_spec
required
string (Package Spec) non-empty
hash_digest
required
string (Hash Digest) non-empty
Index Url (string) or Index Url (null) (Index Url)
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "package_spec": "string",
  • "hash_digest": "string",
  • "index_url": "string"
}

Response samples

Content type
application/json
{
  • "package": {
    },
  • "install_duration_seconds": 0,
  • "audit_event_id": "string"
}

Get Gate Package

Get one installed gate-package by name (FR-90).

Authorizations:
BearerAuthOAuth2Login
path Parameters
name
required
string (Name)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "package_spec": "string",
  • "version": "string",
  • "hash_digest": "string",
  • "index_url": "string",
  • "installed_at": "2019-08-24T14:15:22Z",
  • "installed_by": "string",
  • "last_replaced_at": "2019-08-24T14:15:22Z",
  • "status": "active",
  • "classpaths": [
    ]
}

Replace Gate Package

Atomic in-place replace (FR-89a / T7.5).

Refuses with 409 classpath_drop if the new package would drop a currently-bound classpath. The replace itself is atomic — at most a sub-microsecond filesystem window where the gate code is unavailable (gate-runner fails closed during that window per §4.4.5).

Multi-replica caveat (PR #1754 RE-REVIEW round 4 C2 / round 5 M3): eviction of the cached gate instance + sys.modules entry happens per replica. In multi-Ray-Serve / multi-worker deployments, sibling replicas continue to serve the v1 instance until their next pod restart. The X-Kamiwaza-Gate-Eviction-Scope: local-replica-only response header signals this on every replace response.

To make the new wheel effective on all replicas, run the rolling restart (operator runbook):

kubectl rollout restart deployment/core-scheduler -n kamiwaza
kubectl rollout restart raycluster/core-raycluster -n kamiwaza

Broadcast invalidation (runtime-config epoch bump in cluster_gate_packages checked on every gate lookup) is tracked as a follow-up so the rolling restart can be eliminated; current shape is the light-path "thinnest end-to-end" for M5a per design v0.3.9.

Authorizations:
BearerAuthOAuth2Login
path Parameters
name
required
string (Name)
Request Body schema: application/json
required
package_spec
required
string (Package Spec) non-empty
hash_digest
required
string (Hash Digest) non-empty
Index Url (string) or Index Url (null) (Index Url)
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "package_spec": "string",
  • "hash_digest": "string",
  • "index_url": "string"
}

Response samples

Content type
application/json
{
  • "package": {
    },
  • "install_duration_seconds": 0,
  • "audit_event_id": "string"
}

Uninstall Gate Package

Uninstall (FR-90). Refuses with 409 uninstall_blocked if any active Cluster.executionGate or Dataset.gate binding references a classpath from the package.

Authorizations:
BearerAuthOAuth2Login
path Parameters
name
required
string (Name)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

attribute-schema

Declare Attribute

PUT idempotent declare — registers an attribute in the realm vocabulary.

Auth: AdminUser + NativeRealmRequired (§4.4.3.1 row 1). Returns the AttributeSchema in declared state. Re-declaring with an identical shape is a no-op. Shape change on already-declared state returns 400 shape_change_on_declared — deprecate + withdraw first to retire the old shape.

Authorizations:
BearerAuthOAuth2Login
path Parameters
name
required
string (Name)
Request Body schema: application/json
required
type
required
string (Type)
Enum: "string" "int" "bool" "string[]"
sensitive
boolean (Sensitive)
Default: false
authority
string (Authority)
Default: "local_admin"
Enum: "local_admin" "self" "mesh_peer" "system"
schema_version
string (Schema Version) non-empty
Default: "1.0"

Responses

Request samples

Content type
application/json
{
  • "type": "string",
  • "sensitive": false,
  • "authority": "local_admin",
  • "schema_version": "1.0"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "type": "string",
  • "state": "declared",
  • "authority": "local_admin",
  • "sensitive": false,
  • "schema_version": "1.0",
  • "declared_at": "2019-08-24T14:15:22Z",
  • "deprecated_at": "2019-08-24T14:15:22Z",
  • "withdrawn_at": "2019-08-24T14:15:22Z",
  • "declared_by": "string"
}

Delete Attribute Schema

DELETE — deprecate (default) or withdraw (force=true).

Auth: AdminUser + NativeRealmRequired (§4.4.3.1 row 1).

Response shape: {state, subjects_holding_value} so the SDK can surface the post-transition state to the operator.

Authorizations:
BearerAuthOAuth2Login
path Parameters
name
required
string (Name)
query Parameters
force
boolean (Force)
Default: false

When false (default), transitions declared → deprecated. When true, transitions to withdrawn (KC user-profile entry + mapper removed; refused if subjects_holding_value > 0 unless force=true).

subjects_holding_value
integer (Subjects Holding Value) >= 0
Default: 0

Caller-supplied count of subjects currently holding a value for this attribute. Default 0. force=true with non-zero count is allowed and audited; force=false with non-zero count returns 409.

Responses

Response samples

Content type
application/json
{ }

List Attribute Schemas

GET — list the declared vocabulary.

Auth: ViewerUser (admins + ReBAC-allowed viewers can discover the contract surface). Mesh-origin viewers ARE allowed — federation peers may need to discover a clusters's vocabulary to plan cross-cluster gate compatibility (OQ-13 contract surface).

Authorizations:
BearerAuthOAuth2Login
query Parameters
include_deprecated
boolean (Include Deprecated)
Default: true

Include deprecated entries in the response. Withdrawn entries are tombstoned at the KC layer and never appear here.

Responses

Response samples

Content type
application/json
{
  • "attributes": [
    ],
  • "schema_version": "v0.3.6"
}

mesh

Proxy Mesh

Authorizations:
BearerAuthOAuth2Login
path Parameters
cluster_selector
required
string (Cluster Selector)
path
required
string (Path)

Responses

Response samples

Content type
application/json
null

Proxy Mesh

Authorizations:
BearerAuthOAuth2Login
path Parameters
cluster_selector
required
string (Cluster Selector)
path
required
string (Path)

Responses

Response samples

Content type
application/json
null

Proxy Mesh

Authorizations:
BearerAuthOAuth2Login
path Parameters
cluster_selector
required
string (Cluster Selector)
path
required
string (Path)

Responses

Response samples

Content type
application/json
null

Proxy Mesh

Authorizations:
BearerAuthOAuth2Login
path Parameters
cluster_selector
required
string (Cluster Selector)
path
required
string (Path)

Responses

Response samples

Content type
application/json
null

Proxy Mesh

Authorizations:
BearerAuthOAuth2Login
path Parameters
cluster_selector
required
string (Cluster Selector)
path
required
string (Path)

Responses

Response samples

Content type
application/json
null

Proxy Mesh

Authorizations:
BearerAuthOAuth2Login
path Parameters
cluster_selector
required
string (Cluster Selector)
path
required
string (Path)

Responses

Response samples

Content type
application/json
null

Proxy Mesh

Authorizations:
BearerAuthOAuth2Login
path Parameters
cluster_selector
required
string (Cluster Selector)
path
required
string (Path)

Responses

Response samples

Content type
application/json
null

Proxy Mesh

Authorizations:
BearerAuthOAuth2Login
path Parameters
cluster_selector
required
string (Cluster Selector)
path
required
string (Path)

Responses

Response samples

Content type
application/json
null

Proxy Mesh

Authorizations:
BearerAuthOAuth2Login
path Parameters
cluster_selector
required
string (Cluster Selector)
path
required
string (Path)

Responses

Response samples

Content type
application/json
null

Proxy Mesh

Authorizations:
BearerAuthOAuth2Login
path Parameters
cluster_selector
required
string (Cluster Selector)
path
required
string (Path)

Responses

Response samples

Content type
application/json
null

Proxy Mesh

Authorizations:
BearerAuthOAuth2Login
path Parameters
cluster_selector
required
string (Cluster Selector)
path
required
string (Path)

Responses

Response samples

Content type
application/json
null

Proxy Mesh

Authorizations:
BearerAuthOAuth2Login
path Parameters
cluster_selector
required
string (Cluster Selector)
path
required
string (Path)

Responses

Response samples

Content type
application/json
null

Proxy Mesh

Authorizations:
BearerAuthOAuth2Login
path Parameters
cluster_selector
required
string (Cluster Selector)
path
required
string (Path)

Responses

Response samples

Content type
application/json
null

Proxy Mesh

Authorizations:
BearerAuthOAuth2Login
path Parameters
cluster_selector
required
string (Cluster Selector)
path
required
string (Path)

Responses

Response samples

Content type
application/json
null

activity

Get Recent Activity

Endpoint to list all recent activities.

Returns: List[Activity]: A list of recent activities.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
[
  • {
    }
]

ingestion

Health

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
null

Health

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
null

Run Active

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
source_type
required
string (Source Type)

Type of source (e.g., 's3', 'postgres')

object (Kwargs)

Source-specific parameters

Responses

Request samples

Content type
application/json
{
  • "source_type": "string",
  • "kwargs": { }
}

Response samples

Content type
application/json
null

Run Active

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
source_type
required
string (Source Type)

Type of source (e.g., 's3', 'postgres')

object (Kwargs)

Source-specific parameters

Responses

Request samples

Content type
application/json
{
  • "source_type": "string",
  • "kwargs": { }
}

Response samples

Content type
application/json
null

Emit

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
required
object (Mcp)

Metadata Change Proposal

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "mcp": { }
}

Response samples

Content type
application/json
null

Emit

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
required
object (Mcp)

Metadata Change Proposal

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "mcp": { }
}

Response samples

Content type
application/json
null

Add Job

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
job_id
required
string (Job Id)

Unique job identifier

schedule
required
string (Schedule)

Cron schedule expression

source_type
required
string (Source Type)

Type of source

object (Conn Args)

Connection arguments

Responses

Request samples

Content type
application/json
{
  • "job_id": "string",
  • "schedule": "string",
  • "source_type": "string",
  • "conn_args": { }
}

Response samples

Content type
application/json
null

Add Job

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
job_id
required
string (Job Id)

Unique job identifier

schedule
required
string (Schedule)

Cron schedule expression

source_type
required
string (Source Type)

Type of source

object (Conn Args)

Connection arguments

Responses

Request samples

Content type
application/json
{
  • "job_id": "string",
  • "schedule": "string",
  • "source_type": "string",
  • "conn_args": { }
}

Response samples

Content type
application/json
null

Status

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string (Job Id)

Responses

Response samples

Content type
application/json
null

Status

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string (Job Id)

Responses

Response samples

Content type
application/json
null

dde-connectors

List Connectors

Authorizations:
BearerAuthOAuth2Login
query Parameters
limit
integer (Limit) [ 1 .. 100 ]
Default: 50
offset
integer (Offset) >= 0
Default: 0
Source Type (string) or Source Type (null) (Source Type)
Enabled (boolean) or Enabled (null) (Enabled)
Tag (string) or Tag (null) (Tag)
Workroom Id (string) or Workroom Id (null) (Workroom Id)

Filter by workroom ID

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

List Connectors

Authorizations:
BearerAuthOAuth2Login
query Parameters
limit
integer (Limit) [ 1 .. 100 ]
Default: 50
offset
integer (Offset) >= 0
Default: 0
Source Type (string) or Source Type (null) (Source Type)
Enabled (boolean) or Enabled (null) (Enabled)
Tag (string) or Tag (null) (Tag)
Workroom Id (string) or Workroom Id (null) (Workroom Id)

Filter by workroom ID

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Create Connector

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name)
source_type
required
string (Source Type)
connector_type
required
string (Connector Type)
Description (string) or Description (null) (Description)
tags
Array of strings (Tags)
allowed_roles
Array of strings (Allowed Roles)
require_encryption
boolean (Require Encryption)
Default: true
system_high
string (System High)
Default: "UNCLASSIFIED"

System-high classification for this connector

Default Security Marking (string) or Default Security Marking (null) (Default Security Marking)

Default ICISM/CAPCO marking applied when documents lack explicit markings

required
object (Connection Config)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "source_type": "string",
  • "connector_type": "string",
  • "description": "string",
  • "tags": [
    ],
  • "allowed_roles": [
    ],
  • "require_encryption": true,
  • "system_high": "UNCLASSIFIED",
  • "default_security_marking": "string",
  • "connection_config": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "source_type": "string",
  • "connector_type": "string",
  • "description": "string",
  • "tags": [
    ],
  • "allowed_roles": [
    ],
  • "require_encryption": true,
  • "enabled": true,
  • "system_high": "string",
  • "default_security_marking": "string",
  • "last_ingestion_at": "2019-08-24T14:15:22Z",
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "error_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "string"
}

Create Connector

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name)
source_type
required
string (Source Type)
connector_type
required
string (Connector Type)
Description (string) or Description (null) (Description)
tags
Array of strings (Tags)
allowed_roles
Array of strings (Allowed Roles)
require_encryption
boolean (Require Encryption)
Default: true
system_high
string (System High)
Default: "UNCLASSIFIED"

System-high classification for this connector

Default Security Marking (string) or Default Security Marking (null) (Default Security Marking)

Default ICISM/CAPCO marking applied when documents lack explicit markings

required
object (Connection Config)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "source_type": "string",
  • "connector_type": "string",
  • "description": "string",
  • "tags": [
    ],
  • "allowed_roles": [
    ],
  • "require_encryption": true,
  • "system_high": "UNCLASSIFIED",
  • "default_security_marking": "string",
  • "connection_config": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "source_type": "string",
  • "connector_type": "string",
  • "description": "string",
  • "tags": [
    ],
  • "allowed_roles": [
    ],
  • "require_encryption": true,
  • "enabled": true,
  • "system_high": "string",
  • "default_security_marking": "string",
  • "last_ingestion_at": "2019-08-24T14:15:22Z",
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "error_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "string"
}

Get Connector

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "source_type": "string",
  • "connector_type": "string",
  • "description": "string",
  • "tags": [
    ],
  • "allowed_roles": [
    ],
  • "require_encryption": true,
  • "enabled": true,
  • "system_high": "string",
  • "default_security_marking": "string",
  • "last_ingestion_at": "2019-08-24T14:15:22Z",
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "error_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "string"
}

Get Connector

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "source_type": "string",
  • "connector_type": "string",
  • "description": "string",
  • "tags": [
    ],
  • "allowed_roles": [
    ],
  • "require_encryption": true,
  • "enabled": true,
  • "system_high": "string",
  • "default_security_marking": "string",
  • "last_ingestion_at": "2019-08-24T14:15:22Z",
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "error_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "string"
}

Update Connector

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Array of Allowed Roles (strings) or Allowed Roles (null) (Allowed Roles)
Require Encryption (boolean) or Require Encryption (null) (Require Encryption)
Enabled (boolean) or Enabled (null) (Enabled)
Connection Config (object) or Connection Config (null) (Connection Config)
System High (string) or System High (null) (System High)
Default Security Marking (string) or Default Security Marking (null) (Default Security Marking)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "tags": [
    ],
  • "allowed_roles": [
    ],
  • "require_encryption": true,
  • "enabled": true,
  • "connection_config": { },
  • "system_high": "string",
  • "default_security_marking": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "source_type": "string",
  • "connector_type": "string",
  • "description": "string",
  • "tags": [
    ],
  • "allowed_roles": [
    ],
  • "require_encryption": true,
  • "enabled": true,
  • "system_high": "string",
  • "default_security_marking": "string",
  • "last_ingestion_at": "2019-08-24T14:15:22Z",
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "error_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "string"
}

Update Connector

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Array of Tags (strings) or Tags (null) (Tags)
Array of Allowed Roles (strings) or Allowed Roles (null) (Allowed Roles)
Require Encryption (boolean) or Require Encryption (null) (Require Encryption)
Enabled (boolean) or Enabled (null) (Enabled)
Connection Config (object) or Connection Config (null) (Connection Config)
System High (string) or System High (null) (System High)
Default Security Marking (string) or Default Security Marking (null) (Default Security Marking)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "tags": [
    ],
  • "allowed_roles": [
    ],
  • "require_encryption": true,
  • "enabled": true,
  • "connection_config": { },
  • "system_high": "string",
  • "default_security_marking": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "source_type": "string",
  • "connector_type": "string",
  • "description": "string",
  • "tags": [
    ],
  • "allowed_roles": [
    ],
  • "require_encryption": true,
  • "enabled": true,
  • "system_high": "string",
  • "default_security_marking": "string",
  • "last_ingestion_at": "2019-08-24T14:15:22Z",
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "error_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "string"
}

Delete Connector

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "source_type": "string",
  • "connector_type": "string",
  • "description": "string",
  • "tags": [
    ],
  • "allowed_roles": [
    ],
  • "require_encryption": true,
  • "enabled": true,
  • "system_high": "string",
  • "default_security_marking": "string",
  • "last_ingestion_at": "2019-08-24T14:15:22Z",
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "error_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "string"
}

Delete Connector

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "source_type": "string",
  • "connector_type": "string",
  • "description": "string",
  • "tags": [
    ],
  • "allowed_roles": [
    ],
  • "require_encryption": true,
  • "enabled": true,
  • "system_high": "string",
  • "default_security_marking": "string",
  • "last_ingestion_at": "2019-08-24T14:15:22Z",
  • "last_success_at": "2019-08-24T14:15:22Z",
  • "error_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "string"
}

Trigger Ingest

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)

Responses

Response samples

Content type
application/json
{
  • "status": "queued"
}

Trigger Ingest

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)

Responses

Response samples

Content type
application/json
{
  • "status": "queued"
}

dde-documents

Create Document

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
source_id
required
string <uuid> (Source Id)
source_ref
required
string (Source Ref)
item_type
string (Item Type)
Default: "document"
Job Id (string) or Job Id (null) (Job Id)
Job Name (string) or Job Name (null) (Job Name)
Job Config (object) or Job Config (null) (Job Config)
Security Marking (string) or Security Marking (null) (Security Marking)
object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "source_id": "ae50a35c-df42-4eff-ba26-f8bc28d2af81",
  • "source_ref": "string",
  • "item_type": "document",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "job_name": "string",
  • "job_config": { },
  • "security_marking": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "source_id": "ae50a35c-df42-4eff-ba26-f8bc28d2af81",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "source_ref": "string",
  • "item_type": "string",
  • "title": "string",
  • "description": "string",
  • "content_type": "string",
  • "size_bytes": 0,
  • "tags": [
    ],
  • "categories": [
    ],
  • "language": "string",
  • "classification": "string",
  • "security_marking": "string",
  • "handling_caveats": [
    ],
  • "control_markings": [
    ],
  • "sci_controls": [
    ],
  • "dissemination_controls": [
    ],
  • "releasable_to": [
    ],
  • "entities": { },
  • "indexed_at": "2019-08-24T14:15:22Z",
  • "content_date": "2019-08-24T14:15:22Z",
  • "confidence_score": 0,
  • "completeness_score": 0,
  • "access_count": 0
}

Create Document

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
source_id
required
string <uuid> (Source Id)
source_ref
required
string (Source Ref)
item_type
string (Item Type)
Default: "document"
Job Id (string) or Job Id (null) (Job Id)
Job Name (string) or Job Name (null) (Job Name)
Job Config (object) or Job Config (null) (Job Config)
Security Marking (string) or Security Marking (null) (Security Marking)
object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "source_id": "ae50a35c-df42-4eff-ba26-f8bc28d2af81",
  • "source_ref": "string",
  • "item_type": "document",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "job_name": "string",
  • "job_config": { },
  • "security_marking": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "source_id": "ae50a35c-df42-4eff-ba26-f8bc28d2af81",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "source_ref": "string",
  • "item_type": "string",
  • "title": "string",
  • "description": "string",
  • "content_type": "string",
  • "size_bytes": 0,
  • "tags": [
    ],
  • "categories": [
    ],
  • "language": "string",
  • "classification": "string",
  • "security_marking": "string",
  • "handling_caveats": [
    ],
  • "control_markings": [
    ],
  • "sci_controls": [
    ],
  • "dissemination_controls": [
    ],
  • "releasable_to": [
    ],
  • "entities": { },
  • "indexed_at": "2019-08-24T14:15:22Z",
  • "content_date": "2019-08-24T14:15:22Z",
  • "confidence_score": 0,
  • "completeness_score": 0,
  • "access_count": 0
}

List Documents

Authorizations:
BearerAuthOAuth2Login
query Parameters
source_id
required
string <uuid> (Source Id)
limit
integer (Limit) [ 1 .. 100 ]
Default: 20
offset
integer (Offset) >= 0
Default: 0
Item Type (string) or Item Type (null) (Item Type)
Tag (string) or Tag (null) (Tag)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0,
  • "rejections": [
    ]
}

List Documents

Authorizations:
BearerAuthOAuth2Login
query Parameters
source_id
required
string <uuid> (Source Id)
limit
integer (Limit) [ 1 .. 100 ]
Default: 20
offset
integer (Offset) >= 0
Default: 0
Item Type (string) or Item Type (null) (Item Type)
Tag (string) or Tag (null) (Tag)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0,
  • "rejections": [
    ]
}

Get Document

Authorizations:
BearerAuthOAuth2Login
path Parameters
document_id
required
string <uuid> (Document Id)
query Parameters
source_id
required
string <uuid> (Source Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "source_id": "ae50a35c-df42-4eff-ba26-f8bc28d2af81",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "source_ref": "string",
  • "item_type": "string",
  • "title": "string",
  • "description": "string",
  • "content_type": "string",
  • "size_bytes": 0,
  • "tags": [
    ],
  • "categories": [
    ],
  • "language": "string",
  • "classification": "string",
  • "security_marking": "string",
  • "handling_caveats": [
    ],
  • "control_markings": [
    ],
  • "sci_controls": [
    ],
  • "dissemination_controls": [
    ],
  • "releasable_to": [
    ],
  • "entities": { },
  • "indexed_at": "2019-08-24T14:15:22Z",
  • "content_date": "2019-08-24T14:15:22Z",
  • "confidence_score": 0,
  • "completeness_score": 0,
  • "access_count": 0
}

Get Document

Authorizations:
BearerAuthOAuth2Login
path Parameters
document_id
required
string <uuid> (Document Id)
query Parameters
source_id
required
string <uuid> (Source Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "source_id": "ae50a35c-df42-4eff-ba26-f8bc28d2af81",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "source_ref": "string",
  • "item_type": "string",
  • "title": "string",
  • "description": "string",
  • "content_type": "string",
  • "size_bytes": 0,
  • "tags": [
    ],
  • "categories": [
    ],
  • "language": "string",
  • "classification": "string",
  • "security_marking": "string",
  • "handling_caveats": [
    ],
  • "control_markings": [
    ],
  • "sci_controls": [
    ],
  • "dissemination_controls": [
    ],
  • "releasable_to": [
    ],
  • "entities": { },
  • "indexed_at": "2019-08-24T14:15:22Z",
  • "content_date": "2019-08-24T14:15:22Z",
  • "confidence_score": 0,
  • "completeness_score": 0,
  • "access_count": 0
}

retrieval

Create Retrieval Job

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
dataset_urn
required
string (Dataset Urn)

Catalog URN identifying the dataset

Transport (string) or Transport (null) (Transport)
Default: "auto"

Preferred transport ('auto', 'inline', 'sse', 'grpc')

Limit Rows (integer) or Limit Rows (null) (Limit Rows)

Maximum number of rows to materialise (if applicable)

Offset (integer) or Offset (null) (Offset)
Filters (object) or Filters (null) (Filters)
Options (object) or Options (null) (Options)

Backend-specific options (e.g., kafka bootstrap servers)

Array of Columns (strings) or Columns (null) (Columns)
Credential Override (string) or Credential Override (null) (Credential Override)

Caller-provided credential to access the dataset

Format Hint (string) or Format Hint (null) (Format Hint)

Optional hint for dataset format (parquet,csv,json,binary,text,slack)

Batch Size (integer) or Batch Size (null) (Batch Size)

Preferred batch size for streaming transports

Sdk Session (string) or Sdk Session (null) (Sdk Session)

Identifier supplied by the SDK to aid telemetry

Responses

Request samples

Content type
application/json
{
  • "dataset_urn": "string",
  • "transport": "auto",
  • "limit_rows": 1,
  • "offset": 0,
  • "filters": { },
  • "options": { },
  • "columns": [
    ],
  • "credential_override": "pa$$word",
  • "format_hint": "string",
  • "batch_size": 1,
  • "sdk_session": "string"
}

Response samples

Content type
application/json
{
  • "job_id": "string",
  • "transport": "inline",
  • "status": "string",
  • "dataset": {
    },
  • "inline": {
    },
  • "grpc": {
    }
}

Create Retrieval Job

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
dataset_urn
required
string (Dataset Urn)

Catalog URN identifying the dataset

Transport (string) or Transport (null) (Transport)
Default: "auto"

Preferred transport ('auto', 'inline', 'sse', 'grpc')

Limit Rows (integer) or Limit Rows (null) (Limit Rows)

Maximum number of rows to materialise (if applicable)

Offset (integer) or Offset (null) (Offset)
Filters (object) or Filters (null) (Filters)
Options (object) or Options (null) (Options)

Backend-specific options (e.g., kafka bootstrap servers)

Array of Columns (strings) or Columns (null) (Columns)
Credential Override (string) or Credential Override (null) (Credential Override)

Caller-provided credential to access the dataset

Format Hint (string) or Format Hint (null) (Format Hint)

Optional hint for dataset format (parquet,csv,json,binary,text,slack)

Batch Size (integer) or Batch Size (null) (Batch Size)

Preferred batch size for streaming transports

Sdk Session (string) or Sdk Session (null) (Sdk Session)

Identifier supplied by the SDK to aid telemetry

Responses

Request samples

Content type
application/json
{
  • "dataset_urn": "string",
  • "transport": "auto",
  • "limit_rows": 1,
  • "offset": 0,
  • "filters": { },
  • "options": { },
  • "columns": [
    ],
  • "credential_override": "pa$$word",
  • "format_hint": "string",
  • "batch_size": 1,
  • "sdk_session": "string"
}

Response samples

Content type
application/json
{
  • "job_id": "string",
  • "transport": "inline",
  • "status": "string",
  • "dataset": {
    },
  • "inline": {
    },
  • "grpc": {
    }
}

List Retrieval Jobs

List retrieval jobs (ENG-4707 / T5.30 / FR-85).

Native admin sees all jobs; non-admin requesters see only their own (matches the per-job ownership check on get_status / cancel). Mesh callers are scoped to their own requester URN — preserves the isolation property the existing retrieval endpoints use.

Authorizations:
BearerAuthOAuth2Login
query Parameters
limit
integer (Limit)
Default: 100
offset
integer (Offset)
Default: 0

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Retrieval Jobs

List retrieval jobs (ENG-4707 / T5.30 / FR-85).

Native admin sees all jobs; non-admin requesters see only their own (matches the per-job ownership check on get_status / cancel). Mesh callers are scoped to their own requester URN — preserves the isolation property the existing retrieval endpoints use.

Authorizations:
BearerAuthOAuth2Login
query Parameters
limit
integer (Limit)
Default: 100
offset
integer (Offset)
Default: 0

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Cancel Retrieval Job

Cancel a retrieval job (ENG-4709 / T5.32 / FR-84).

Marks the job as CANCELED in the DB. Ownership is enforced — a non-admin requester can only cancel their own jobs. Returns the updated job status.

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)

Responses

Response samples

Content type
application/json
{
  • "job_id": "string",
  • "status": "string",
  • "transport": "inline",
  • "dataset": {
    },
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Cancel Retrieval Job

Cancel a retrieval job (ENG-4709 / T5.32 / FR-84).

Marks the job as CANCELED in the DB. Ownership is enforced — a non-admin requester can only cancel their own jobs. Returns the updated job status.

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)

Responses

Response samples

Content type
application/json
{
  • "job_id": "string",
  • "status": "string",
  • "transport": "inline",
  • "dataset": {
    },
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Retrieval Job

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)

Responses

Response samples

Content type
application/json
{
  • "job_id": "string",
  • "status": "string",
  • "transport": "inline",
  • "dataset": {
    },
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Retrieval Job

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)

Responses

Response samples

Content type
application/json
{
  • "job_id": "string",
  • "status": "string",
  • "transport": "inline",
  • "dataset": {
    },
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Stream Retrieval Job

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)

Responses

Response samples

Content type
application/json
null

Stream Retrieval Job

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)

Responses

Response samples

Content type
application/json
null

context

List Vectordbs

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Vectordb Instance

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
name
required
string (Name)

VectorDB instance name

engine
required
string (VectorDBEngine)
Enum: "milvus" "vespa"

VectorDB engine type

Config (object) or Config (null) (Config)

Engine-specific configuration

Workroom Id (string) or Workroom Id (null) (Workroom Id)

Optional workroom scope for the instance

replicas
integer (Replicas)
Default: 1

Number of replicas to deploy

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "engine": "milvus",
  • "config": { },
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "replicas": 1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "engine": "milvus",
  • "status": "pending",
  • "endpoint": "string",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "replicas": 0
}

Get Vectordb Instance

Authorizations:
BearerAuthOAuth2Login
path Parameters
vectordb_id
required
string <uuid> (Vectordb Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "engine": "milvus",
  • "status": "pending",
  • "endpoint": "string",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "replicas": 0
}

Update Vectordb Instance

Authorizations:
BearerAuthOAuth2Login
path Parameters
vectordb_id
required
string <uuid> (Vectordb Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
Config (object) or Config (null) (Config)

Updated engine configuration

Replicas (integer) or Replicas (null) (Replicas)

Updated replica count

Responses

Request samples

Content type
application/json
{
  • "config": { },
  • "replicas": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "engine": "milvus",
  • "status": "pending",
  • "endpoint": "string",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "replicas": 0
}

Delete Vectordb Instance

Authorizations:
BearerAuthOAuth2Login
path Parameters
vectordb_id
required
string <uuid> (Vectordb Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Scale Vectordb Instance

Authorizations:
BearerAuthOAuth2Login
path Parameters
vectordb_id
required
string <uuid> (Vectordb Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
replicas
required
integer (Replicas)

Target replica count

Responses

Request samples

Content type
application/json
{
  • "replicas": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "engine": "milvus",
  • "status": "pending",
  • "endpoint": "string",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "replicas": 0
}

Insert Vectors For Instance

Authorizations:
BearerAuthOAuth2Login
path Parameters
vectordb_id
required
string <uuid> (Vectordb Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

VectorDB instance ID (required for body-based routes)

collection_name
required
string (Collection Name)

Target collection name

vectors
required
Array of numbers (Vectors) [ items ]

Vector payloads

required
Array of objects (Metadata)

Metadata for each vector

Array of Field List (any) or Field List (null) (Field List)

Optional schema field definitions

create_if_missing
boolean (Create If Missing)
Default: true

Create collection if missing

Responses

Request samples

Content type
application/json
{
  • "vectordb_id": "750a6f0f-1262-45ca-b36a-33d95c9c88bc",
  • "collection_name": "string",
  • "vectors": [
    ],
  • "metadata": [
    ],
  • "field_list": [
    ],
  • "create_if_missing": true
}

Response samples

Content type
application/json
{
  • "inserted_count": 0
}

Insert Vectors

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

VectorDB instance ID (required for body-based routes)

collection_name
required
string (Collection Name)

Target collection name

vectors
required
Array of numbers (Vectors) [ items ]

Vector payloads

required
Array of objects (Metadata)

Metadata for each vector

Array of Field List (any) or Field List (null) (Field List)

Optional schema field definitions

create_if_missing
boolean (Create If Missing)
Default: true

Create collection if missing

Responses

Request samples

Content type
application/json
{
  • "vectordb_id": "750a6f0f-1262-45ca-b36a-33d95c9c88bc",
  • "collection_name": "string",
  • "vectors": [
    ],
  • "metadata": [
    ],
  • "field_list": [
    ],
  • "create_if_missing": true
}

Response samples

Content type
application/json
{
  • "inserted_count": 0
}

Query Vectors For Instance

Authorizations:
BearerAuthOAuth2Login
path Parameters
vectordb_id
required
string <uuid> (Vectordb Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

VectorDB instance ID (required for body-based routes)

collection_name
required
string (Collection Name)

Target collection name

vectors
required
Array of numbers (Vectors) [ items ]

Query vectors

limit
integer (Limit)
Default: 10

Maximum results to return

Params (object) or Params (null) (Params)

Backend-specific search parameters

Array of Output Fields (strings) or Output Fields (null) (Output Fields)

Fields to return with each result

Responses

Request samples

Content type
application/json
{
  • "vectordb_id": "750a6f0f-1262-45ca-b36a-33d95c9c88bc",
  • "collection_name": "string",
  • "vectors": [
    ],
  • "limit": 10,
  • "params": { },
  • "output_fields": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Query Vectors

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

VectorDB instance ID (required for body-based routes)

collection_name
required
string (Collection Name)

Target collection name

vectors
required
Array of numbers (Vectors) [ items ]

Query vectors

limit
integer (Limit)
Default: 10

Maximum results to return

Params (object) or Params (null) (Params)

Backend-specific search parameters

Array of Output Fields (strings) or Output Fields (null) (Output Fields)

Fields to return with each result

Responses

Request samples

Content type
application/json
{
  • "vectordb_id": "750a6f0f-1262-45ca-b36a-33d95c9c88bc",
  • "collection_name": "string",
  • "vectors": [
    ],
  • "limit": 10,
  • "params": { },
  • "output_fields": [
    ]
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

List Ontologies

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Ontology Instance

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
name
required
string (Name)

Ontology instance name

backend
required
string (OntologyBackend)
Enum: "graphiti" "graphrag" "openspg" "kag"

Ontology backend type

Config (object) or Config (null) (Config)

Backend-specific configuration

Workroom Id (string) or Workroom Id (null) (Workroom Id)

Optional workroom scope for the instance

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "backend": "graphiti",
  • "config": { },
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "backend": "graphiti",
  • "status": "pending",
  • "status_reason": "string",
  • "status_details": { },
  • "ingestion_status": "none",
  • "ingestion_error": "string",
  • "ingestion_updated_at": "2019-08-24T14:15:22Z",
  • "endpoint": "string",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Ontology Instance

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "backend": "graphiti",
  • "status": "pending",
  • "status_reason": "string",
  • "status_details": { },
  • "ingestion_status": "none",
  • "ingestion_error": "string",
  • "ingestion_updated_at": "2019-08-24T14:15:22Z",
  • "endpoint": "string",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Ontology Instance

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Get Global Context Settings

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "omniparse": {
    }
}

Patch Global Context Settings

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
UpdateOmniParseGlobalSettings (object) or null
Reason (string) or Reason (null) (Reason)

Responses

Request samples

Content type
application/json
{
  • "omniparse": {
    },
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "omniparse": {
    }
}

List Omniparse Instances

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Omniparse Instance

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
name
required
string (Name)

OmniParse instance name

template_name
string (Template Name)
Default: "tool-omniparse"

Tool template name for OmniParse deployment

Config (object) or Config (null) (Config)

OmniParse environment configuration

Workroom Id (string) or Workroom Id (null) (Workroom Id)

Optional workroom scope for the instance

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "template_name": "tool-omniparse",
  • "config": { },
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "status": "pending",
  • "endpoint": "string",
  • "deployment_id": "6ef0ac85-9892-4664-a2a5-58bf2af5a8a6",
  • "template_name": "string",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Omniparse Instance

Authorizations:
BearerAuthOAuth2Login
path Parameters
omniparse_id
required
string <uuid> (Omniparse Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "status": "pending",
  • "endpoint": "string",
  • "deployment_id": "6ef0ac85-9892-4664-a2a5-58bf2af5a8a6",
  • "template_name": "string",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Omniparse Instance

Authorizations:
BearerAuthOAuth2Login
path Parameters
omniparse_id
required
string <uuid> (Omniparse Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
Config (object) or Config (null) (Config)

Updated OmniParse environment configuration

Any of
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "config": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "status": "pending",
  • "endpoint": "string",
  • "deployment_id": "6ef0ac85-9892-4664-a2a5-58bf2af5a8a6",
  • "template_name": "string",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Omniparse Instance

Authorizations:
BearerAuthOAuth2Login
path Parameters
omniparse_id
required
string <uuid> (Omniparse Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Get Audio Readiness

Authorizations:
BearerAuthOAuth2Login
query Parameters
Mime Type (string) or Mime Type (null) (Mime Type)

Optional MIME, e.g. audio/aiff

Filename (string) or Filename (null) (Filename)

Optional filename context

header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "ready": true,
  • "code": "string",
  • "message": "string",
  • "remediation": "string",
  • "details": { }
}

List Collections

List all collections in the workroom.

Returns collections with workroom isolation - only shows collections belonging to the specified workroom.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

Optional VectorDB instance to target explicitly

header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Collection

Create a new collection in the workroom.

Collection names are prefixed with workroom_id for isolation: ws_{workroom_id}_{collection_name}

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 64 ] characters ^[a-zA-Z0-9_-]+$

Collection name (alphanumeric, underscores, hyphens)

dimension
integer (Dimension) [ 32 .. 4096 ]
Default: 384

Vector dimension

Description (string) or Description (null) (Description)

Collection description

Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

Optional VectorDB instance to target explicitly

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "dimension": 384,
  • "description": "string",
  • "vectordb_id": "750a6f0f-1262-45ca-b36a-33d95c9c88bc"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "display_name": "string",
  • "workroom_id": "string",
  • "vector_count": 0,
  • "dimension": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "description": "string"
}

Get Collection

Get collection information by name.

Authorizations:
BearerAuthOAuth2Login
path Parameters
collection_name
required
string (Collection Name)
query Parameters
Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

Optional VectorDB instance to target explicitly

header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "display_name": "string",
  • "workroom_id": "string",
  • "vector_count": 0,
  • "dimension": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "description": "string"
}

Delete Collection

Delete a collection from the workroom.

This permanently removes all vectors in the collection.

Authorizations:
BearerAuthOAuth2Login
path Parameters
collection_name
required
string (Collection Name)
query Parameters
Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

Optional VectorDB instance to target explicitly

header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Create Pipeline Job

Create and start a new pipeline job.

The pipeline processes files through:

  1. Extract: Convert files to text
  2. Chunk: Split text into chunks
  3. Embed: Generate vector embeddings
  4. Index: Store vectors in Milvus

Processing runs in the background. Poll the job status endpoint or configure a callback URL to be notified on completion.

Returns 201 for newly created jobs, 200 for idempotent replays.

Args: request: Pipeline job creation request with files and config workroom_id: Workroom identifier from header background_tasks: FastAPI background tasks

Returns: Created PipelineJob with pending status

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
required
Array of objects (Files) non-empty

Files to process

object (PipelineConfig-Input)

Pipeline configuration

CallbackConfig (object) or null

Optional callback configuration for job completion notification

Idempotency Key (string) or Idempotency Key (null) (Idempotency Key)

Optional client idempotency key. Same key + workroom returns existing job.

force
boolean (Force)
Default: false

When true, reprocess inline file content even if source tracking shows the same source URN and content hash were already indexed.

Responses

Request samples

Content type
application/json
{
  • "files": [
    ],
  • "config": {
    },
  • "callback": {
    },
  • "idempotency_key": "string",
  • "force": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "collection_name": "string",
  • "status": "pending",
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error": "string",
  • "diagnostics": { },
  • "created_by": "string",
  • "idempotency_key": "string",
  • "file_results": [
    ],
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "request_snapshot": {
    }
}

List Pipeline Jobs

List pipeline jobs for the workroom.

Args: workroom_id: Workroom identifier from header status: Filter by job status (pending, running, completed, failed) limit: Maximum number of jobs to return (default 50, max 100) offset: Number of jobs to skip for pagination (default 0)

Returns: List of PipelineJob objects sorted by creation time (newest first)

Authorizations:
BearerAuthOAuth2Login
query Parameters
Status (string) or Status (null) (Status)
limit
integer (Limit)
Default: 50
offset
integer (Offset)
Default: 0
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Supported File Types

Get list of supported file types for pipeline processing.

Returns: List of supported file extensions (e.g., [".pdf", ".docx", ".txt"])

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get Import Options

Get aggregated import options for Kaizen's provider-neutral import shell.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "supported_mime_types": [
    ],
  • "available_stages": [
    ]
}

Evaluate Import Options

Evaluate selected source descriptors against Context import rules.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
Array of objects (Sources)
object (PipelineConfig-Input)

Configuration for pipeline execution.

Responses

Request samples

Content type
application/json
{
  • "sources": [
    ],
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "supported_mime_types": [
    ],
  • "available_stages": [
    ],
  • "normalized_config": {
    },
  • "can_submit": false,
  • "validation_issues": [
    ]
}

Create Source Import Job

Create and start a provider-neutral source import job.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
required
Array of objects (Sources) non-empty

Provider-neutral source descriptors selected upstream.

object (PipelineConfig-Input)

Pipeline configuration to apply to all selected sources.

CallbackConfig (object) or null

Optional callback configuration for job completion notification

Idempotency Key (string) or Idempotency Key (null) (Idempotency Key)

Optional client idempotency key. Same key + workroom returns existing job.

force
boolean (Force)
Default: false

When true, force reprocessing for replayable source imports even if future dedup layers would otherwise skip them.

Responses

Request samples

Content type
application/json
{
  • "sources": [
    ],
  • "config": {
    },
  • "callback": {
    },
  • "idempotency_key": "string",
  • "force": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "collection_name": "string",
  • "status": "pending",
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error": "string",
  • "diagnostics": { },
  • "created_by": "string",
  • "idempotency_key": "string",
  • "file_results": [
    ],
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "request_snapshot": {
    }
}

List Import Items

List workroom-wide source import inventory/history items.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total_items": 0,
  • "truncated": false
}

Rerun Import Items

Rerun selected inventory items using their recorded source descriptors.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
item_keys
required
Array of strings (Item Keys) non-empty
PipelineConfig (object) or null
CallbackConfig (object) or null
Idempotency Key (string) or Idempotency Key (null) (Idempotency Key)
force
boolean (Force)
Default: true

Responses

Request samples

Content type
application/json
{
  • "item_keys": [
    ],
  • "config": {
    },
  • "callback": {
    },
  • "idempotency_key": "string",
  • "force": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "collection_name": "string",
  • "status": "pending",
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error": "string",
  • "diagnostics": { },
  • "created_by": "string",
  • "idempotency_key": "string",
  • "file_results": [
    ],
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "request_snapshot": {
    }
}

List Pipeline Job Items

List canonical per-item statuses for one pipeline job.

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "items": [
    ]
}

Get Pipeline Job

Get pipeline job status and progress.

Args: job_id: Pipeline job identifier workroom_id: Workroom identifier from header

Returns: PipelineJob with current status and progress

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "collection_name": "string",
  • "status": "pending",
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error": "string",
  • "diagnostics": { },
  • "created_by": "string",
  • "idempotency_key": "string",
  • "file_results": [
    ],
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "request_snapshot": {
    }
}

Delete Pipeline Job

Delete or cancel a pipeline job.

For pending/running jobs: cancels them first, then deletes. For completed/failed/cancelled jobs: deletes them.

Args: job_id: Pipeline job identifier workroom_id: Workroom identifier from header

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Cancel Pipeline Job

Cancel a pipeline job without deleting its recorded history.

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "collection_name": "string",
  • "status": "pending",
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error": "string",
  • "diagnostics": { },
  • "created_by": "string",
  • "idempotency_key": "string",
  • "file_results": [
    ],
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "request_snapshot": {
    }
}

Retry Pipeline Job

Retry failed or incomplete items from a replayable source import job.

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
CallbackConfig (object) or null
Idempotency Key (string) or Idempotency Key (null) (Idempotency Key)
Force (boolean) or Force (null) (Force)

Optional override for replay force behavior.

Responses

Request samples

Content type
application/json
{
  • "callback": {
    },
  • "idempotency_key": "string",
  • "force": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "collection_name": "string",
  • "status": "pending",
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error": "string",
  • "diagnostics": { },
  • "created_by": "string",
  • "idempotency_key": "string",
  • "file_results": [
    ],
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "request_snapshot": {
    }
}

Rerun Pipeline Job

Rerun all recorded source descriptors from a prior source import job.

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
CallbackConfig (object) or null
Idempotency Key (string) or Idempotency Key (null) (Idempotency Key)
Force (boolean) or Force (null) (Force)

Optional override for replay force behavior.

Responses

Request samples

Content type
application/json
{
  • "callback": {
    },
  • "idempotency_key": "string",
  • "force": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "collection_name": "string",
  • "status": "pending",
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error": "string",
  • "diagnostics": { },
  • "created_by": "string",
  • "idempotency_key": "string",
  • "file_results": [
    ],
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "request_snapshot": {
    }
}

Search

Dispatch /search to legacy or unified behavior without breaking old clients.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
Example
{
  • "query": "string",
  • "results": [
    ],
  • "total_count": 0,
  • "search_time_ms": 0,
  • "collections_searched": [
    ],
  • "partial_failures": [
    ],
  • "search_mode": "auto",
  • "is_exact_query": false,
  • "exact_match_count": 0,
  • "semantic_neighbor_count": 0,
  • "semantic_neighbors": [
    ]
}

Unified Search

Unified search with progressive enrichment.

Base: vector search only (fast) format_context=true: adds LLM-ready context string synthesize=true: LLM synthesis with [N] citations max_iterations > 1: iterative query refinement enable_graph_search=true: includes knowledge graph

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
query
required
string (Query) [ 1 .. 10000 ] characters

Search query text

top_k
integer (Top K) [ 1 .. 100 ]
Default: 10

Number of results to return

Collection Name (string) or Collection Name (null) (Collection Name)

Single collection to search (None = search all workroom collections)

Array of Collection Names (strings) or Collection Names (null) (Collection Names)

Multiple collections to search

Score Threshold (number) or Score Threshold (null) (Score Threshold)

Minimum similarity score threshold

Filters (object) or Filters (null) (Filters)

Metadata filters. In agentic mode these apply only to VectorDB document retrieval, not knowledge graph results.

Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

Specific VectorDB instance UUID to target

Array of Vectordb Ids (strings) or Vectordb Ids (null) (Vectordb Ids)

Multiple VectorDB instance UUIDs for agentic search

search_mode
string (Search Mode)
Default: "auto"
Enum: "auto" "semantic" "exact"

Search interpretation: auto detects exact marker/quoted queries, semantic preserves vector search, exact filters returned candidates to chunks containing the literal query needle.

format_context
boolean (Format Context)
Default: false

Return LLM-ready formatted context string

synthesize
boolean (Synthesize)
Default: false

LLM synthesis with [N] source citations

max_iterations
integer (Max Iterations) [ 1 .. 10 ]
Default: 1

Refinement iterations (1 = no refinement)

relevance_threshold
number (Relevance Threshold) [ 0 .. 1 ]
Default: 0.7

Agentic relevance threshold used when synthesize, iterative refinement, or graph search routes the request to agentic search

enable_graph_search
boolean (Enable Graph Search)
Default: false

Include knowledge graph search

Ontology Id (string) or Ontology Id (null) (Ontology Id)

Ontology instance UUID for graph search

Array of Group Ids (strings) or Group Ids (null) (Group Ids)

Knowledge graph group IDs

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "top_k": 10,
  • "collection_name": "string",
  • "collection_names": [
    ],
  • "score_threshold": 1,
  • "filters": { },
  • "vectordb_id": "750a6f0f-1262-45ca-b36a-33d95c9c88bc",
  • "vectordb_ids": [
    ],
  • "search_mode": "auto",
  • "format_context": false,
  • "synthesize": false,
  • "max_iterations": 1,
  • "relevance_threshold": 0.7,
  • "enable_graph_search": false,
  • "ontology_id": "2a85698e-3f76-4aad-89d1-465b6cb21ca9",
  • "group_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "query": "string",
  • "results": [
    ],
  • "sources": [
    ],
  • "total_count": 0,
  • "search_time_ms": 0,
  • "collections_searched": [
    ],
  • "partial_failures": [
    ],
  • "search_mode": "auto",
  • "is_exact_query": false,
  • "exact_match_count": 0,
  • "semantic_neighbor_count": 0,
  • "semantic_neighbors": [
    ],
  • "context": "string",
  • "synthesis": "string",
  • "citations": [
    ],
  • "graph_results": 0,
  • "graph_facts": [
    ],
  • "iterations": 0,
  • "iteration_history": [
    ],
  • "refinement_queries": [
    ]
}

Semantic Search Legacy Deprecated

Deprecated: Use POST /search instead.

Perform semantic search across workroom collections.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
query
required
string (Query) [ 1 .. 10000 ] characters

Search query text

Collection Name (string) or Collection Name (null) (Collection Name)

Collection to search (None = search all workroom collections)

top_k
integer (Top K) [ 1 .. 100 ]
Default: 10

Number of results to return

Score Threshold (number) or Score Threshold (null) (Score Threshold)

Minimum score threshold

Filters (object) or Filters (null) (Filters)

Metadata filters

Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

Optional VectorDB instance to target explicitly

search_mode
string (Search Mode)
Default: "auto"
Enum: "auto" "semantic" "exact"

Search interpretation: auto detects exact marker/quoted queries, semantic preserves pure vector search, exact filters returned candidates to chunks containing the literal query needle.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "collection_name": "string",
  • "top_k": 10,
  • "score_threshold": 1,
  • "filters": { },
  • "vectordb_id": "750a6f0f-1262-45ca-b36a-33d95c9c88bc",
  • "search_mode": "auto"
}

Response samples

Content type
application/json
{
  • "query": "string",
  • "results": [
    ],
  • "total_count": 0,
  • "search_time_ms": 0,
  • "collections_searched": [
    ],
  • "partial_failures": [
    ],
  • "search_mode": "auto",
  • "is_exact_query": false,
  • "exact_match_count": 0,
  • "semantic_neighbor_count": 0,
  • "semantic_neighbors": [
    ]
}

Retrieve Context Legacy Deprecated

Deprecated: Use POST /search with format_context=true instead.

Retrieve context for RAG (Retrieval-Augmented Generation).

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
query
required
string (Query) [ 1 .. 10000 ] characters

User query for RAG

Collection Name (string) or Collection Name (null) (Collection Name)

Single collection to search, parity with /search. Honored only when collection_names is not provided. An explicit collection is searched directly, which is required to reach worker-written raw collections that the managed enumeration does not surface.

Array of Collection Names (strings) or Collection Names (null) (Collection Names)

Collections to search (None = all workroom collections)

top_k
integer (Top K) [ 1 .. 50 ]
Default: 5

Number of sources to retrieve

Score Threshold (number) or Score Threshold (null) (Score Threshold)

Minimum relevance score; None applies no floor (parity with /search).

max_context_length
integer (Max Context Length) [ 500 .. 32000 ]
Default: 4000

Maximum context length in characters

Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

Optional VectorDB instance to target explicitly

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "collection_name": "string",
  • "collection_names": [
    ],
  • "top_k": 5,
  • "score_threshold": 1,
  • "max_context_length": 4000,
  • "vectordb_id": "750a6f0f-1262-45ca-b36a-33d95c9c88bc"
}

Response samples

Content type
application/json
{
  • "context": "string",
  • "sources": [
    ],
  • "query": "string",
  • "retrieval_time_ms": 0
}

Agentic Search Legacy Deprecated

Deprecated: Use POST /search with synthesize=true instead.

Run agentic retrieval search via REST. Fixes I1: this endpoint was previously missing its @router.post() decorator.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
query
required
string (Query) [ 1 .. 10000 ] characters

Search query text

vectordb_ids
Array of strings <uuid> (Vectordb Ids) [ items <uuid > ]

VectorDB instance IDs to search

collection
string (Collection) <= 128 characters
Default: "default"

Target collection name

Array of Collection Names (strings) or Collection Names (null) (Collection Names)

Backward-compatible collection list. Only a single collection is supported for agentic retrieval.

Collection Name (string) or Collection Name (null) (Collection Name)

Single target collection, parity with /search and /retrieve. Takes precedence over the 'collection' default; a one-item collection_names list still wins. Agentic retrieval targets exactly one collection.

Array of Group Ids (strings) or Group Ids (null) (Group Ids)

Optional knowledge graph groups

Ontology Id (string) or Ontology Id (null) (Ontology Id)

Optional ontology instance ID for graph search

max_iterations
integer (Max Iterations) [ 1 .. 10 ]
Default: 3

Max refinement iterations

relevance_threshold
number (Relevance Threshold) [ 0 .. 1 ]
Default: 0.7

Minimum relevance threshold

top_k
integer (Top K) [ 1 .. 100 ]
Default: 10

Top results to return

Filters (object) or Filters (null) (Filters)

Metadata filters for VectorDB document retrieval only. Knowledge graph results are not filtered.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "vectordb_ids": [
    ],
  • "collection": "default",
  • "collection_names": [
    ],
  • "collection_name": "string",
  • "group_ids": [
    ],
  • "ontology_id": "2a85698e-3f76-4aad-89d1-465b6cb21ca9",
  • "max_iterations": 3,
  • "relevance_threshold": 0.7,
  • "top_k": 10,
  • "filters": { }
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "iterations": 1,
  • "iteration_history": [
    ],
  • "refinement_queries": [
    ],
  • "synthesis": "string",
  • "citations": [
    ],
  • "latency_ms": 0,
  • "total_results": 0
}

Add Knowledge

Add knowledge to the graph from messages.

This endpoint processes messages and extracts entities and relationships automatically using the knowledge graph backend (e.g., Graphiti's LLM).

Args: ontology_id: Ontology instance UUID request: Request with group_id and messages

Returns: AddKnowledgeResult with number of messages processed

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
group_id
required
string (Group Id)

Knowledge group/conversation identifier

required
Array of objects (Messages)

Messages to process

Entity Types (object) or Entity Types (null) (Entity Types)

Optional entity-type schema to constrain extraction to a known type system. Omit for unconstrained extraction (default, backward-compatible behavior).

Array of Excluded Entity Types (strings) or Excluded Entity Types (null) (Excluded Entity Types)

Entity types to suppress, e.g. ["Entity"] to drop Graphiti's built-in catch-all so extraction is constrained to the supplied types rather than merely biased toward them.

Responses

Request samples

Content type
application/json
{
  • "group_id": "string",
  • "messages": [
    ],
  • "entity_types": {
    },
  • "excluded_entity_types": [
    ]
}

Response samples

Content type
application/json
{
  • "added_count": 0,
  • "group_id": "string",
  • "result": { },
  • "error": "string"
}

Add Entity

Add an explicit entity to the knowledge graph.

Use this endpoint when you want to add a specific entity without relying on automatic extraction from messages.

Args: ontology_id: Ontology instance UUID request: Entity creation request

Returns: AddEntityResult with entity_id

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
group_id
required
string (Group Id)

Knowledge group identifier

name
required
string (Name)

Entity name

entity_type
required
string (Entity Type)

Entity type (person, org, concept, etc.)

Summary (string) or Summary (null) (Summary)

Entity description/summary

Properties (object) or Properties (null) (Properties)

Additional entity properties

Responses

Request samples

Content type
application/json
{
  • "group_id": "string",
  • "name": "string",
  • "entity_type": "string",
  • "summary": "string",
  • "properties": { }
}

Response samples

Content type
application/json
{
  • "entity_id": "string",
  • "name": "string",
  • "success": true,
  • "error": "string"
}

Get Workroom Subgraph

Workroom subgraph seed call for the Ontology Graph Viewer.

Calls the GraphitiAdapter's bounded-subgraph endpoint (T3.16) and applies the C9 source-attribution join when available. Caps enforced via Pydantic Query bounds (max_nodes <= 500, max_edges <= 2500).

Cross-workroom guard: a path workroom_id that the caller is not authorized for returns 404 (matches FE expectation per system design line 1161).

Note: source_attribution wiring is deferred (O-R3 — production DB-backed IngestionLogReader pending). Until that lands the response always carries sources: [] even when the substrate returns edges. The FE drawer surfaces "No sources attributed" in that case.

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
workroom_id
required
string <uuid> (Workroom Id)
query Parameters
max_nodes
integer (Max Nodes) [ 1 .. 500 ]
Default: 500
max_edges
integer (Max Edges) [ 1 .. 2500 ]
Default: 2500

Responses

Response samples

Content type
application/json
{
  • "nodes": [
    ],
  • "edges": [
    ],
  • "truncated": false,
  • "sources": [
    ]
}

Search Knowledge

Search the knowledge graph for relevant facts.

Args: ontology_id: Ontology instance UUID request: Search request with query and group_ids

Returns: KnowledgeSearchResult with matching facts

Cross-workroom guard: this route is addressed by ontology id only, so the caller's authorized X-Workroom-ID need not match the workroom the ontology actually belongs to. Without a guard, an ontology owned by another workroom slips past header authz and the workroom-scoped instance lookup downstream fails with a swallowed ValueError that surfaces as a generic 500 — making a denial indistinguishable from a real server error. Derive the ontology's owning workroom from the row and authorize the caller against it, collapsing 403 → 404 to hide existence (matching get_workroom_subgraph / the model-bindings route). A missing ontology collapses to the same 404 so cross-workroom and not-found are indistinguishable; 401/503 propagate unchanged because they carry no resource-existence signal.

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
query
required
string (Query)

Search query text

group_ids
required
Array of strings (Group Ids)

Knowledge groups to search

max_results
integer (Max Results) [ 1 .. 100 ]
Default: 10

Maximum results to return

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "group_ids": [
    ],
  • "max_results": 10
}

Response samples

Content type
application/json
{
  • "facts": [
    ],
  • "query": "string",
  • "total_count": 0,
  • "sources": [
    ]
}

Get Memory

Get RAG context from the knowledge graph.

This is the primary endpoint for retrieving context to augment LLM prompts with knowledge from the graph.

Args: ontology_id: Ontology instance UUID request: Memory request with group_id and query

Returns: MemoryResult with facts and related entities

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
group_id
required
string (Group Id)

Knowledge group identifier

query
required
string (Query)

Query to find relevant context

max_facts
integer (Max Facts) [ 1 .. 50 ]
Default: 10

Maximum facts to return

Responses

Request samples

Content type
application/json
{
  • "group_id": "string",
  • "query": "string",
  • "max_facts": 10
}

Response samples

Content type
application/json
{
  • "facts": [
    ],
  • "entities": [
    ],
  • "episodes": [
    ],
  • "group_id": "string"
}

Get Episodes

Get recent episodes for a knowledge group.

Args: ontology_id: Ontology instance UUID group_id: Knowledge group identifier last_n: Number of recent episodes to retrieve

Returns: EpisodesResult with episodes

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
group_id
required
string (Group Id)
query Parameters
last_n
integer (Last N) [ 1 .. 100 ]
Default: 10
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "episodes": [
    ],
  • "group_id": "string",
  • "count": 0
}

Delete Group

Delete a knowledge group and all its data.

WARNING: This is destructive and cannot be undone.

Args: ontology_id: Ontology instance UUID group_id: Group identifier to delete

Returns: DeleteGroupResult with success status

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
group_id
required
string (Group Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "group_id": "string",
  • "success": true
}

Update Model Bindings

Operator-driven pin update for a Graphiti ontology's chat / embedding bindings.

Pin a chat or embedding capability to a specific deployment by ID, or clear an existing pin (deployment_id=null) and let the binding reconciler resume auto-resolution. See system design Section 4.2.5 for the full state matrix.

Authorization is path-scoped: the workroom is derived from DBOntologyInstance.workroom_id (not from X-Workroom-ID) so the caller cannot escalate by sending a foreign header. Admins bypass; because this is a write/operator action (it patches the Graphiti extension env via the reconciler), non-admins must hold a write-caliber relation (owner/editor) on the derived workroom — read-only membership (viewer) is not sufficient.

Validation order (each step's failure short-circuits the next):

  1. Authentication (ContextWriter — admin OR user).
  2. Ontology existence + workroom derivation. Any pre-authz lookup failure (missing, foreign workroom, global-scoped) collapses to 404 so the existence of an ontology in another workroom can neither be probed nor confirmed by an unprivileged caller. This mirrors the path-scoped pattern in get_workroom_subgraph (system design Section 4.4.5 / OWASP A01).
  3. Workroom authorization for the path-derived workroom id: (a) read membership — non-members collapse to 404 (privacy); (b) write-caliber owner/editor — a confirmed read-only member (viewer) is rejected with 403 (existence already known to them, so not collapsed to 404). Membership outage → 503.
  4. Capability classification (chat vs embedding) for each requested deployment_id. 422 on mismatch.
  5. Embedding identity check against the existing pin. 422 on cross-model attempt.
  6. Reconciler runs: probes route, persists _managed_bindings, patches K8s extension env. Successful K8s rollout → 200. K8s rollout failure → reconciler rolls back the binding and raises ModelRouteUnavailableError → 503 + Retry-After. Operator-pinned deployment unroutable → 503 + Retry-After.
Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
Request Body schema: application/json
required
BindingUpdate (object) or null

Chat-capability pin update. Omit to leave unchanged; supply with deployment_id=null to clear an existing pin.

BindingUpdate (object) or null

Embedding-capability pin update. Omit to leave unchanged; supply with deployment_id=null to clear an existing pin.

Responses

Request samples

Content type
application/json
{
  • "chat": {
    },
  • "embedding": {
    }
}

Response samples

Content type
application/json
{
  • "ontology_id": "2a85698e-3f76-4aad-89d1-465b6cb21ca9",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "chat": {
    },
  • "embedding": {
    },
  • "runtime_status": { },
  • "rollout": {
    },
  • "message": "string"
}

Health Check

Check health of an ontology instance.

Args: ontology_id: Ontology instance UUID

Returns: Health status

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{ }

Upload File

Upload a file for processing through the context pipeline.

Streams the uploaded file to a temp location, validates size and type, then creates a pipeline job for background processing.

Args: file: Multipart file upload. workroom_id: Workroom identifier from header. background_tasks: FastAPI background tasks. collection_name: Target collection name (optional). source_urn: Source URN for tracking (optional).

Returns: Created PipelineJob with pending status.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Collection Name (string) or Collection Name (null) (Collection Name)
Source Urn (string) or Source Urn (null) (Source Urn)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: multipart/form-data
required
file
required
string <application/octet-stream> (File)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "collection_name": "string",
  • "status": "pending",
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error": "string",
  • "diagnostics": { },
  • "created_by": "string",
  • "idempotency_key": "string",
  • "file_results": [
    ],
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "request_snapshot": {
    }
}

Create Raw File

Store a raw file directly into workroom-scoped object storage.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
filename
required
string (Filename) [ 1 .. 255 ] characters

Original filename for the stored raw file.

content_base64
required
string (Content Base64) [ 4 .. 139810136 ] characters

Base64-encoded raw file bytes. Must encode at least one byte (min 4 characters); decoded payload must not exceed the configured max_file_size_mb limit.

Content Type (string) or Content Type (null) (Content Type)

Optional MIME type. Defaults to a filename-based guess.

Source Urn (string) or Source Urn (null) (Source Urn)

Optional source URN associated with the raw file. The inline-create verb only accepts inline:// and workspace:// schemes; connector-mediated provenance (m365://, connector://) must come from ingestion paths that verify the upstream.

Source Kind (string) or Source Kind (null) (Source Kind)

Optional source mode. Permitted values: inline, workspace.

object (Source Ref)

Optional connector/source reference metadata.

object (Metadata)

Optional caller-supplied metadata to persist with the raw file.

Responses

Request samples

Content type
application/json
{
  • "filename": "string",
  • "content_base64": "string",
  • "content_type": "string",
  • "source_urn": "string",
  • "source_kind": "string",
  • "source_ref": { },
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "source_urn": "string",
  • "filename": "string",
  • "content_type": "string",
  • "size_bytes": 0,
  • "checksum_sha256": "string",
  • "source_kind": "string",
  • "source_ref": { },
  • "s3_uri": "string",
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "string",
  • "download_url": "string"
}

List Raw Files

List raw files stored for a workroom.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Source Urn (string) or Source Urn (null) (Source Urn)

Filter by source URN

Job Id (string) or Job Id (null) (Job Id)

Filter by pipeline job ID

Connector Id (string) or Connector Id (null) (Connector Id)

Filter to RawFiles ingested via a single connector instance (matches the connector_id segment of the source URN: urn:kamiwaza:context-source:<provider>:<connector_id>:...).

limit
integer (Limit) [ 1 .. 200 ]
Default: 50
offset
integer (Offset) >= 0
Default: 0
include_markings
boolean (Include Markings)
Default: false

When true, each row includes markings: list[str] aggregated per source from DDE document metadata (with connector default as fallback). Default-off preserves the existing call shape for callers that do not need markings. See system design §4.2.13.

header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "count": 0
}

Get Raw File

Get one raw-file metadata record by ID and workroom scope.

Authorizations:
BearerAuthOAuth2Login
path Parameters
file_id
required
string <uuid> (File Id)
query Parameters
include_download_url
boolean (Include Download Url)
Default: false

Include a pre-signed download URL when S3 metadata exists

Expires Seconds (integer) or Expires Seconds (null) (Expires Seconds)

Override pre-signed URL TTL in seconds

header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "source_urn": "string",
  • "filename": "string",
  • "content_type": "string",
  • "size_bytes": 0,
  • "checksum_sha256": "string",
  • "source_kind": "string",
  • "source_ref": { },
  • "s3_uri": "string",
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "string",
  • "download_url": "string"
}

Update Raw File

Update the content of a plain-text raw file (C13).

Edit access: any ContextWriter member of the workroom (no author-only gate). See system design v0.1.4 §3.8.5 + spikes/t1.1-c13-verb-shape.md for the locked contract.

Authorizations:
BearerAuthOAuth2Login
path Parameters
file_id
required
string <uuid> (File Id)
header Parameters
If-Match (string) or If-Match (null) (If-Match)

Optional concurrency-control token (the file's updated_at ISO-8601 string from a previous response). If provided and stale, returns 409 with the current token in the response detail.

X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
content
required
string (Content) <= 65535 characters

Replacement content for the raw file. Must be non-empty after .strip() and must not exceed RAW_FILE_MAX_EDIT_BYTES (65535 bytes) when UTF-8 encoded — see object_storage_service for the canonical byte-level constant. Pydantic enforces a character cap of 65535 here; the route enforces the exact UTF-8-byte cap after encoding.

Responses

Request samples

Content type
application/json
{
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "source_urn": "string",
  • "filename": "string",
  • "content_type": "string",
  • "size_bytes": 0,
  • "checksum_sha256": "string",
  • "source_kind": "string",
  • "source_ref": { },
  • "s3_uri": "string",
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "string",
  • "download_url": "string"
}

Get Document Download Url

Get a presigned download URL for an original document.

Looks up the document by source URN in the source tracking database, then generates a presigned S3 URL for download.

Requires S3 storage to be enabled.

Authorizations:
BearerAuthOAuth2Login
path Parameters
source_urn
required
string (Source Urn)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "download_url": "string",
  • "filename": "string",
  • "content_hash": "string",
  • "source_urn": "string"
}

Download Raw File

Raw-file detail with a browser-reachable (public) presigned download URL.

Authorizations:
BearerAuthOAuth2Login
path Parameters
file_id
required
string <uuid> (File Id)
query Parameters
Expires Seconds (integer) or Expires Seconds (null) (Expires Seconds)

Override pre-signed URL TTL in seconds

header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "source_urn": "string",
  • "filename": "string",
  • "content_type": "string",
  • "size_bytes": 0,
  • "checksum_sha256": "string",
  • "source_kind": "string",
  • "source_ref": { },
  • "s3_uri": "string",
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "string",
  • "download_url": "string"
}

Download Document

Original-document browser-reachable (public) presigned download URL.

Authorizations:
BearerAuthOAuth2Login
path Parameters
source_urn
required
string (Source Urn)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "download_url": "string",
  • "filename": "string",
  • "content_hash": "string",
  • "source_urn": "string"
}

Set Embedding Model

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
group_id
required
string (Group Id) [ 1 .. 255 ] characters
Embedding Deployment Id (string) or Embedding Deployment Id (null) (Embedding Deployment Id)

Deployment to bind for this group_id. Pass null to clear any existing override and let auto-selection take over.

force
boolean (Force)
Default: false

Required when the override would change vector dimensions and thereby invalidate stored vectors. With force=true the server schedules a re-embedding job.

Responses

Request samples

Content type
application/json
{
  • "group_id": "string",
  • "embedding_deployment_id": "9bc4a55e-a75a-44ac-a151-591903486d14",
  • "force": false
}

Response samples

Content type
application/json
{
  • "group_id": "string",
  • "embedding_deployment_id": "9bc4a55e-a75a-44ac-a151-591903486d14",
  • "embedding_model_name": "string",
  • "embedding_dimensions": 0,
  • "source": "override",
  • "healthy": true,
  • "last_verified_at": "2019-08-24T14:15:22Z",
  • "first_used_at": "2019-08-24T14:15:22Z"
}

Get Embedding Model

Authorizations:
BearerAuthOAuth2Login
query Parameters
group_id
required
string (Group Id) [ 1 .. 255 ] characters
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "group_id": "string",
  • "embedding_deployment_id": "9bc4a55e-a75a-44ac-a151-591903486d14",
  • "embedding_model_name": "string",
  • "embedding_dimensions": 0,
  • "source": "override",
  • "healthy": true,
  • "last_verified_at": "2019-08-24T14:15:22Z",
  • "first_used_at": "2019-08-24T14:15:22Z"
}

Health Check

Health check endpoint showing available features.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
null

collections

List Collections

List all collections in the workroom.

Returns collections with workroom isolation - only shows collections belonging to the specified workroom.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

Optional VectorDB instance to target explicitly

header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Collection

Create a new collection in the workroom.

Collection names are prefixed with workroom_id for isolation: ws_{workroom_id}_{collection_name}

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 64 ] characters ^[a-zA-Z0-9_-]+$

Collection name (alphanumeric, underscores, hyphens)

dimension
integer (Dimension) [ 32 .. 4096 ]
Default: 384

Vector dimension

Description (string) or Description (null) (Description)

Collection description

Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

Optional VectorDB instance to target explicitly

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "dimension": 384,
  • "description": "string",
  • "vectordb_id": "750a6f0f-1262-45ca-b36a-33d95c9c88bc"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "display_name": "string",
  • "workroom_id": "string",
  • "vector_count": 0,
  • "dimension": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "description": "string"
}

Get Collection

Get collection information by name.

Authorizations:
BearerAuthOAuth2Login
path Parameters
collection_name
required
string (Collection Name)
query Parameters
Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

Optional VectorDB instance to target explicitly

header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "display_name": "string",
  • "workroom_id": "string",
  • "vector_count": 0,
  • "dimension": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "description": "string"
}

Delete Collection

Delete a collection from the workroom.

This permanently removes all vectors in the collection.

Authorizations:
BearerAuthOAuth2Login
path Parameters
collection_name
required
string (Collection Name)
query Parameters
Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

Optional VectorDB instance to target explicitly

header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

pipelines

Create Pipeline Job

Create and start a new pipeline job.

The pipeline processes files through:

  1. Extract: Convert files to text
  2. Chunk: Split text into chunks
  3. Embed: Generate vector embeddings
  4. Index: Store vectors in Milvus

Processing runs in the background. Poll the job status endpoint or configure a callback URL to be notified on completion.

Returns 201 for newly created jobs, 200 for idempotent replays.

Args: request: Pipeline job creation request with files and config workroom_id: Workroom identifier from header background_tasks: FastAPI background tasks

Returns: Created PipelineJob with pending status

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
required
Array of objects (Files) non-empty

Files to process

object (PipelineConfig-Input)

Pipeline configuration

CallbackConfig (object) or null

Optional callback configuration for job completion notification

Idempotency Key (string) or Idempotency Key (null) (Idempotency Key)

Optional client idempotency key. Same key + workroom returns existing job.

force
boolean (Force)
Default: false

When true, reprocess inline file content even if source tracking shows the same source URN and content hash were already indexed.

Responses

Request samples

Content type
application/json
{
  • "files": [
    ],
  • "config": {
    },
  • "callback": {
    },
  • "idempotency_key": "string",
  • "force": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "collection_name": "string",
  • "status": "pending",
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error": "string",
  • "diagnostics": { },
  • "created_by": "string",
  • "idempotency_key": "string",
  • "file_results": [
    ],
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "request_snapshot": {
    }
}

List Pipeline Jobs

List pipeline jobs for the workroom.

Args: workroom_id: Workroom identifier from header status: Filter by job status (pending, running, completed, failed) limit: Maximum number of jobs to return (default 50, max 100) offset: Number of jobs to skip for pagination (default 0)

Returns: List of PipelineJob objects sorted by creation time (newest first)

Authorizations:
BearerAuthOAuth2Login
query Parameters
Status (string) or Status (null) (Status)
limit
integer (Limit)
Default: 50
offset
integer (Offset)
Default: 0
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Supported File Types

Get list of supported file types for pipeline processing.

Returns: List of supported file extensions (e.g., [".pdf", ".docx", ".txt"])

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get Import Options

Get aggregated import options for Kaizen's provider-neutral import shell.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "supported_mime_types": [
    ],
  • "available_stages": [
    ]
}

Evaluate Import Options

Evaluate selected source descriptors against Context import rules.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
Array of objects (Sources)
object (PipelineConfig-Input)

Configuration for pipeline execution.

Responses

Request samples

Content type
application/json
{
  • "sources": [
    ],
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "supported_mime_types": [
    ],
  • "available_stages": [
    ],
  • "normalized_config": {
    },
  • "can_submit": false,
  • "validation_issues": [
    ]
}

Create Source Import Job

Create and start a provider-neutral source import job.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
required
Array of objects (Sources) non-empty

Provider-neutral source descriptors selected upstream.

object (PipelineConfig-Input)

Pipeline configuration to apply to all selected sources.

CallbackConfig (object) or null

Optional callback configuration for job completion notification

Idempotency Key (string) or Idempotency Key (null) (Idempotency Key)

Optional client idempotency key. Same key + workroom returns existing job.

force
boolean (Force)
Default: false

When true, force reprocessing for replayable source imports even if future dedup layers would otherwise skip them.

Responses

Request samples

Content type
application/json
{
  • "sources": [
    ],
  • "config": {
    },
  • "callback": {
    },
  • "idempotency_key": "string",
  • "force": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "collection_name": "string",
  • "status": "pending",
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error": "string",
  • "diagnostics": { },
  • "created_by": "string",
  • "idempotency_key": "string",
  • "file_results": [
    ],
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "request_snapshot": {
    }
}

List Import Items

List workroom-wide source import inventory/history items.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total_items": 0,
  • "truncated": false
}

Rerun Import Items

Rerun selected inventory items using their recorded source descriptors.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
item_keys
required
Array of strings (Item Keys) non-empty
PipelineConfig (object) or null
CallbackConfig (object) or null
Idempotency Key (string) or Idempotency Key (null) (Idempotency Key)
force
boolean (Force)
Default: true

Responses

Request samples

Content type
application/json
{
  • "item_keys": [
    ],
  • "config": {
    },
  • "callback": {
    },
  • "idempotency_key": "string",
  • "force": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "collection_name": "string",
  • "status": "pending",
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error": "string",
  • "diagnostics": { },
  • "created_by": "string",
  • "idempotency_key": "string",
  • "file_results": [
    ],
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "request_snapshot": {
    }
}

List Pipeline Job Items

List canonical per-item statuses for one pipeline job.

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "items": [
    ]
}

Get Pipeline Job

Get pipeline job status and progress.

Args: job_id: Pipeline job identifier workroom_id: Workroom identifier from header

Returns: PipelineJob with current status and progress

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "collection_name": "string",
  • "status": "pending",
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error": "string",
  • "diagnostics": { },
  • "created_by": "string",
  • "idempotency_key": "string",
  • "file_results": [
    ],
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "request_snapshot": {
    }
}

Delete Pipeline Job

Delete or cancel a pipeline job.

For pending/running jobs: cancels them first, then deletes. For completed/failed/cancelled jobs: deletes them.

Args: job_id: Pipeline job identifier workroom_id: Workroom identifier from header

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Cancel Pipeline Job

Cancel a pipeline job without deleting its recorded history.

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "collection_name": "string",
  • "status": "pending",
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error": "string",
  • "diagnostics": { },
  • "created_by": "string",
  • "idempotency_key": "string",
  • "file_results": [
    ],
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "request_snapshot": {
    }
}

Retry Pipeline Job

Retry failed or incomplete items from a replayable source import job.

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
CallbackConfig (object) or null
Idempotency Key (string) or Idempotency Key (null) (Idempotency Key)
Force (boolean) or Force (null) (Force)

Optional override for replay force behavior.

Responses

Request samples

Content type
application/json
{
  • "callback": {
    },
  • "idempotency_key": "string",
  • "force": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "collection_name": "string",
  • "status": "pending",
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error": "string",
  • "diagnostics": { },
  • "created_by": "string",
  • "idempotency_key": "string",
  • "file_results": [
    ],
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "request_snapshot": {
    }
}

Rerun Pipeline Job

Rerun all recorded source descriptors from a prior source import job.

Authorizations:
BearerAuthOAuth2Login
path Parameters
job_id
required
string <uuid> (Job Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
CallbackConfig (object) or null
Idempotency Key (string) or Idempotency Key (null) (Idempotency Key)
Force (boolean) or Force (null) (Force)

Optional override for replay force behavior.

Responses

Request samples

Content type
application/json
{
  • "callback": {
    },
  • "idempotency_key": "string",
  • "force": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "collection_name": "string",
  • "status": "pending",
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error": "string",
  • "diagnostics": { },
  • "created_by": "string",
  • "idempotency_key": "string",
  • "file_results": [
    ],
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "request_snapshot": {
    }
}

search

Search

Dispatch /search to legacy or unified behavior without breaking old clients.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
Example
{
  • "query": "string",
  • "results": [
    ],
  • "total_count": 0,
  • "search_time_ms": 0,
  • "collections_searched": [
    ],
  • "partial_failures": [
    ],
  • "search_mode": "auto",
  • "is_exact_query": false,
  • "exact_match_count": 0,
  • "semantic_neighbor_count": 0,
  • "semantic_neighbors": [
    ]
}

Unified Search

Unified search with progressive enrichment.

Base: vector search only (fast) format_context=true: adds LLM-ready context string synthesize=true: LLM synthesis with [N] citations max_iterations > 1: iterative query refinement enable_graph_search=true: includes knowledge graph

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
query
required
string (Query) [ 1 .. 10000 ] characters

Search query text

top_k
integer (Top K) [ 1 .. 100 ]
Default: 10

Number of results to return

Collection Name (string) or Collection Name (null) (Collection Name)

Single collection to search (None = search all workroom collections)

Array of Collection Names (strings) or Collection Names (null) (Collection Names)

Multiple collections to search

Score Threshold (number) or Score Threshold (null) (Score Threshold)

Minimum similarity score threshold

Filters (object) or Filters (null) (Filters)

Metadata filters. In agentic mode these apply only to VectorDB document retrieval, not knowledge graph results.

Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

Specific VectorDB instance UUID to target

Array of Vectordb Ids (strings) or Vectordb Ids (null) (Vectordb Ids)

Multiple VectorDB instance UUIDs for agentic search

search_mode
string (Search Mode)
Default: "auto"
Enum: "auto" "semantic" "exact"

Search interpretation: auto detects exact marker/quoted queries, semantic preserves vector search, exact filters returned candidates to chunks containing the literal query needle.

format_context
boolean (Format Context)
Default: false

Return LLM-ready formatted context string

synthesize
boolean (Synthesize)
Default: false

LLM synthesis with [N] source citations

max_iterations
integer (Max Iterations) [ 1 .. 10 ]
Default: 1

Refinement iterations (1 = no refinement)

relevance_threshold
number (Relevance Threshold) [ 0 .. 1 ]
Default: 0.7

Agentic relevance threshold used when synthesize, iterative refinement, or graph search routes the request to agentic search

enable_graph_search
boolean (Enable Graph Search)
Default: false

Include knowledge graph search

Ontology Id (string) or Ontology Id (null) (Ontology Id)

Ontology instance UUID for graph search

Array of Group Ids (strings) or Group Ids (null) (Group Ids)

Knowledge graph group IDs

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "top_k": 10,
  • "collection_name": "string",
  • "collection_names": [
    ],
  • "score_threshold": 1,
  • "filters": { },
  • "vectordb_id": "750a6f0f-1262-45ca-b36a-33d95c9c88bc",
  • "vectordb_ids": [
    ],
  • "search_mode": "auto",
  • "format_context": false,
  • "synthesize": false,
  • "max_iterations": 1,
  • "relevance_threshold": 0.7,
  • "enable_graph_search": false,
  • "ontology_id": "2a85698e-3f76-4aad-89d1-465b6cb21ca9",
  • "group_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "query": "string",
  • "results": [
    ],
  • "sources": [
    ],
  • "total_count": 0,
  • "search_time_ms": 0,
  • "collections_searched": [
    ],
  • "partial_failures": [
    ],
  • "search_mode": "auto",
  • "is_exact_query": false,
  • "exact_match_count": 0,
  • "semantic_neighbor_count": 0,
  • "semantic_neighbors": [
    ],
  • "context": "string",
  • "synthesis": "string",
  • "citations": [
    ],
  • "graph_results": 0,
  • "graph_facts": [
    ],
  • "iterations": 0,
  • "iteration_history": [
    ],
  • "refinement_queries": [
    ]
}

Semantic Search Legacy Deprecated

Deprecated: Use POST /search instead.

Perform semantic search across workroom collections.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
query
required
string (Query) [ 1 .. 10000 ] characters

Search query text

Collection Name (string) or Collection Name (null) (Collection Name)

Collection to search (None = search all workroom collections)

top_k
integer (Top K) [ 1 .. 100 ]
Default: 10

Number of results to return

Score Threshold (number) or Score Threshold (null) (Score Threshold)

Minimum score threshold

Filters (object) or Filters (null) (Filters)

Metadata filters

Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

Optional VectorDB instance to target explicitly

search_mode
string (Search Mode)
Default: "auto"
Enum: "auto" "semantic" "exact"

Search interpretation: auto detects exact marker/quoted queries, semantic preserves pure vector search, exact filters returned candidates to chunks containing the literal query needle.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "collection_name": "string",
  • "top_k": 10,
  • "score_threshold": 1,
  • "filters": { },
  • "vectordb_id": "750a6f0f-1262-45ca-b36a-33d95c9c88bc",
  • "search_mode": "auto"
}

Response samples

Content type
application/json
{
  • "query": "string",
  • "results": [
    ],
  • "total_count": 0,
  • "search_time_ms": 0,
  • "collections_searched": [
    ],
  • "partial_failures": [
    ],
  • "search_mode": "auto",
  • "is_exact_query": false,
  • "exact_match_count": 0,
  • "semantic_neighbor_count": 0,
  • "semantic_neighbors": [
    ]
}

Retrieve Context Legacy Deprecated

Deprecated: Use POST /search with format_context=true instead.

Retrieve context for RAG (Retrieval-Augmented Generation).

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
query
required
string (Query) [ 1 .. 10000 ] characters

User query for RAG

Collection Name (string) or Collection Name (null) (Collection Name)

Single collection to search, parity with /search. Honored only when collection_names is not provided. An explicit collection is searched directly, which is required to reach worker-written raw collections that the managed enumeration does not surface.

Array of Collection Names (strings) or Collection Names (null) (Collection Names)

Collections to search (None = all workroom collections)

top_k
integer (Top K) [ 1 .. 50 ]
Default: 5

Number of sources to retrieve

Score Threshold (number) or Score Threshold (null) (Score Threshold)

Minimum relevance score; None applies no floor (parity with /search).

max_context_length
integer (Max Context Length) [ 500 .. 32000 ]
Default: 4000

Maximum context length in characters

Vectordb Id (string) or Vectordb Id (null) (Vectordb Id)

Optional VectorDB instance to target explicitly

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "collection_name": "string",
  • "collection_names": [
    ],
  • "top_k": 5,
  • "score_threshold": 1,
  • "max_context_length": 4000,
  • "vectordb_id": "750a6f0f-1262-45ca-b36a-33d95c9c88bc"
}

Response samples

Content type
application/json
{
  • "context": "string",
  • "sources": [
    ],
  • "query": "string",
  • "retrieval_time_ms": 0
}

Agentic Search Legacy Deprecated

Deprecated: Use POST /search with synthesize=true instead.

Run agentic retrieval search via REST. Fixes I1: this endpoint was previously missing its @router.post() decorator.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
query
required
string (Query) [ 1 .. 10000 ] characters

Search query text

vectordb_ids
Array of strings <uuid> (Vectordb Ids) [ items <uuid > ]

VectorDB instance IDs to search

collection
string (Collection) <= 128 characters
Default: "default"

Target collection name

Array of Collection Names (strings) or Collection Names (null) (Collection Names)

Backward-compatible collection list. Only a single collection is supported for agentic retrieval.

Collection Name (string) or Collection Name (null) (Collection Name)

Single target collection, parity with /search and /retrieve. Takes precedence over the 'collection' default; a one-item collection_names list still wins. Agentic retrieval targets exactly one collection.

Array of Group Ids (strings) or Group Ids (null) (Group Ids)

Optional knowledge graph groups

Ontology Id (string) or Ontology Id (null) (Ontology Id)

Optional ontology instance ID for graph search

max_iterations
integer (Max Iterations) [ 1 .. 10 ]
Default: 3

Max refinement iterations

relevance_threshold
number (Relevance Threshold) [ 0 .. 1 ]
Default: 0.7

Minimum relevance threshold

top_k
integer (Top K) [ 1 .. 100 ]
Default: 10

Top results to return

Filters (object) or Filters (null) (Filters)

Metadata filters for VectorDB document retrieval only. Knowledge graph results are not filtered.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "vectordb_ids": [
    ],
  • "collection": "default",
  • "collection_names": [
    ],
  • "collection_name": "string",
  • "group_ids": [
    ],
  • "ontology_id": "2a85698e-3f76-4aad-89d1-465b6cb21ca9",
  • "max_iterations": 3,
  • "relevance_threshold": 0.7,
  • "top_k": 10,
  • "filters": { }
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "iterations": 1,
  • "iteration_history": [
    ],
  • "refinement_queries": [
    ],
  • "synthesis": "string",
  • "citations": [
    ],
  • "latency_ms": 0,
  • "total_results": 0
}

ontology-operations

Add Knowledge

Add knowledge to the graph from messages.

This endpoint processes messages and extracts entities and relationships automatically using the knowledge graph backend (e.g., Graphiti's LLM).

Args: ontology_id: Ontology instance UUID request: Request with group_id and messages

Returns: AddKnowledgeResult with number of messages processed

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
group_id
required
string (Group Id)

Knowledge group/conversation identifier

required
Array of objects (Messages)

Messages to process

Entity Types (object) or Entity Types (null) (Entity Types)

Optional entity-type schema to constrain extraction to a known type system. Omit for unconstrained extraction (default, backward-compatible behavior).

Array of Excluded Entity Types (strings) or Excluded Entity Types (null) (Excluded Entity Types)

Entity types to suppress, e.g. ["Entity"] to drop Graphiti's built-in catch-all so extraction is constrained to the supplied types rather than merely biased toward them.

Responses

Request samples

Content type
application/json
{
  • "group_id": "string",
  • "messages": [
    ],
  • "entity_types": {
    },
  • "excluded_entity_types": [
    ]
}

Response samples

Content type
application/json
{
  • "added_count": 0,
  • "group_id": "string",
  • "result": { },
  • "error": "string"
}

Add Entity

Add an explicit entity to the knowledge graph.

Use this endpoint when you want to add a specific entity without relying on automatic extraction from messages.

Args: ontology_id: Ontology instance UUID request: Entity creation request

Returns: AddEntityResult with entity_id

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
group_id
required
string (Group Id)

Knowledge group identifier

name
required
string (Name)

Entity name

entity_type
required
string (Entity Type)

Entity type (person, org, concept, etc.)

Summary (string) or Summary (null) (Summary)

Entity description/summary

Properties (object) or Properties (null) (Properties)

Additional entity properties

Responses

Request samples

Content type
application/json
{
  • "group_id": "string",
  • "name": "string",
  • "entity_type": "string",
  • "summary": "string",
  • "properties": { }
}

Response samples

Content type
application/json
{
  • "entity_id": "string",
  • "name": "string",
  • "success": true,
  • "error": "string"
}

Get Workroom Subgraph

Workroom subgraph seed call for the Ontology Graph Viewer.

Calls the GraphitiAdapter's bounded-subgraph endpoint (T3.16) and applies the C9 source-attribution join when available. Caps enforced via Pydantic Query bounds (max_nodes <= 500, max_edges <= 2500).

Cross-workroom guard: a path workroom_id that the caller is not authorized for returns 404 (matches FE expectation per system design line 1161).

Note: source_attribution wiring is deferred (O-R3 — production DB-backed IngestionLogReader pending). Until that lands the response always carries sources: [] even when the substrate returns edges. The FE drawer surfaces "No sources attributed" in that case.

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
workroom_id
required
string <uuid> (Workroom Id)
query Parameters
max_nodes
integer (Max Nodes) [ 1 .. 500 ]
Default: 500
max_edges
integer (Max Edges) [ 1 .. 2500 ]
Default: 2500

Responses

Response samples

Content type
application/json
{
  • "nodes": [
    ],
  • "edges": [
    ],
  • "truncated": false,
  • "sources": [
    ]
}

Search Knowledge

Search the knowledge graph for relevant facts.

Args: ontology_id: Ontology instance UUID request: Search request with query and group_ids

Returns: KnowledgeSearchResult with matching facts

Cross-workroom guard: this route is addressed by ontology id only, so the caller's authorized X-Workroom-ID need not match the workroom the ontology actually belongs to. Without a guard, an ontology owned by another workroom slips past header authz and the workroom-scoped instance lookup downstream fails with a swallowed ValueError that surfaces as a generic 500 — making a denial indistinguishable from a real server error. Derive the ontology's owning workroom from the row and authorize the caller against it, collapsing 403 → 404 to hide existence (matching get_workroom_subgraph / the model-bindings route). A missing ontology collapses to the same 404 so cross-workroom and not-found are indistinguishable; 401/503 propagate unchanged because they carry no resource-existence signal.

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
query
required
string (Query)

Search query text

group_ids
required
Array of strings (Group Ids)

Knowledge groups to search

max_results
integer (Max Results) [ 1 .. 100 ]
Default: 10

Maximum results to return

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "group_ids": [
    ],
  • "max_results": 10
}

Response samples

Content type
application/json
{
  • "facts": [
    ],
  • "query": "string",
  • "total_count": 0,
  • "sources": [
    ]
}

Get Memory

Get RAG context from the knowledge graph.

This is the primary endpoint for retrieving context to augment LLM prompts with knowledge from the graph.

Args: ontology_id: Ontology instance UUID request: Memory request with group_id and query

Returns: MemoryResult with facts and related entities

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
group_id
required
string (Group Id)

Knowledge group identifier

query
required
string (Query)

Query to find relevant context

max_facts
integer (Max Facts) [ 1 .. 50 ]
Default: 10

Maximum facts to return

Responses

Request samples

Content type
application/json
{
  • "group_id": "string",
  • "query": "string",
  • "max_facts": 10
}

Response samples

Content type
application/json
{
  • "facts": [
    ],
  • "entities": [
    ],
  • "episodes": [
    ],
  • "group_id": "string"
}

Get Episodes

Get recent episodes for a knowledge group.

Args: ontology_id: Ontology instance UUID group_id: Knowledge group identifier last_n: Number of recent episodes to retrieve

Returns: EpisodesResult with episodes

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
group_id
required
string (Group Id)
query Parameters
last_n
integer (Last N) [ 1 .. 100 ]
Default: 10
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "episodes": [
    ],
  • "group_id": "string",
  • "count": 0
}

Delete Group

Delete a knowledge group and all its data.

WARNING: This is destructive and cannot be undone.

Args: ontology_id: Ontology instance UUID group_id: Group identifier to delete

Returns: DeleteGroupResult with success status

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
group_id
required
string (Group Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "group_id": "string",
  • "success": true
}

Update Model Bindings

Operator-driven pin update for a Graphiti ontology's chat / embedding bindings.

Pin a chat or embedding capability to a specific deployment by ID, or clear an existing pin (deployment_id=null) and let the binding reconciler resume auto-resolution. See system design Section 4.2.5 for the full state matrix.

Authorization is path-scoped: the workroom is derived from DBOntologyInstance.workroom_id (not from X-Workroom-ID) so the caller cannot escalate by sending a foreign header. Admins bypass; because this is a write/operator action (it patches the Graphiti extension env via the reconciler), non-admins must hold a write-caliber relation (owner/editor) on the derived workroom — read-only membership (viewer) is not sufficient.

Validation order (each step's failure short-circuits the next):

  1. Authentication (ContextWriter — admin OR user).
  2. Ontology existence + workroom derivation. Any pre-authz lookup failure (missing, foreign workroom, global-scoped) collapses to 404 so the existence of an ontology in another workroom can neither be probed nor confirmed by an unprivileged caller. This mirrors the path-scoped pattern in get_workroom_subgraph (system design Section 4.4.5 / OWASP A01).
  3. Workroom authorization for the path-derived workroom id: (a) read membership — non-members collapse to 404 (privacy); (b) write-caliber owner/editor — a confirmed read-only member (viewer) is rejected with 403 (existence already known to them, so not collapsed to 404). Membership outage → 503.
  4. Capability classification (chat vs embedding) for each requested deployment_id. 422 on mismatch.
  5. Embedding identity check against the existing pin. 422 on cross-model attempt.
  6. Reconciler runs: probes route, persists _managed_bindings, patches K8s extension env. Successful K8s rollout → 200. K8s rollout failure → reconciler rolls back the binding and raises ModelRouteUnavailableError → 503 + Retry-After. Operator-pinned deployment unroutable → 503 + Retry-After.
Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
Request Body schema: application/json
required
BindingUpdate (object) or null

Chat-capability pin update. Omit to leave unchanged; supply with deployment_id=null to clear an existing pin.

BindingUpdate (object) or null

Embedding-capability pin update. Omit to leave unchanged; supply with deployment_id=null to clear an existing pin.

Responses

Request samples

Content type
application/json
{
  • "chat": {
    },
  • "embedding": {
    }
}

Response samples

Content type
application/json
{
  • "ontology_id": "2a85698e-3f76-4aad-89d1-465b6cb21ca9",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "chat": {
    },
  • "embedding": {
    },
  • "runtime_status": { },
  • "rollout": {
    },
  • "message": "string"
}

Health Check

Check health of an ontology instance.

Args: ontology_id: Ontology instance UUID

Returns: Health status

Authorizations:
BearerAuthOAuth2Login
path Parameters
ontology_id
required
string <uuid> (Ontology Id)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{ }

upload

Upload File

Upload a file for processing through the context pipeline.

Streams the uploaded file to a temp location, validates size and type, then creates a pipeline job for background processing.

Args: file: Multipart file upload. workroom_id: Workroom identifier from header. background_tasks: FastAPI background tasks. collection_name: Target collection name (optional). source_urn: Source URN for tracking (optional).

Returns: Created PipelineJob with pending status.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Collection Name (string) or Collection Name (null) (Collection Name)
Source Urn (string) or Source Urn (null) (Source Urn)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: multipart/form-data
required
file
required
string <application/octet-stream> (File)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "collection_name": "string",
  • "status": "pending",
  • "progress": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "error": "string",
  • "diagnostics": { },
  • "created_by": "string",
  • "idempotency_key": "string",
  • "file_results": [
    ],
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "request_snapshot": {
    }
}

storage

Create Raw File

Store a raw file directly into workroom-scoped object storage.

Authorizations:
BearerAuthOAuth2Login
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
filename
required
string (Filename) [ 1 .. 255 ] characters

Original filename for the stored raw file.

content_base64
required
string (Content Base64) [ 4 .. 139810136 ] characters

Base64-encoded raw file bytes. Must encode at least one byte (min 4 characters); decoded payload must not exceed the configured max_file_size_mb limit.

Content Type (string) or Content Type (null) (Content Type)

Optional MIME type. Defaults to a filename-based guess.

Source Urn (string) or Source Urn (null) (Source Urn)

Optional source URN associated with the raw file. The inline-create verb only accepts inline:// and workspace:// schemes; connector-mediated provenance (m365://, connector://) must come from ingestion paths that verify the upstream.

Source Kind (string) or Source Kind (null) (Source Kind)

Optional source mode. Permitted values: inline, workspace.

object (Source Ref)

Optional connector/source reference metadata.

object (Metadata)

Optional caller-supplied metadata to persist with the raw file.

Responses

Request samples

Content type
application/json
{
  • "filename": "string",
  • "content_base64": "string",
  • "content_type": "string",
  • "source_urn": "string",
  • "source_kind": "string",
  • "source_ref": { },
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "source_urn": "string",
  • "filename": "string",
  • "content_type": "string",
  • "size_bytes": 0,
  • "checksum_sha256": "string",
  • "source_kind": "string",
  • "source_ref": { },
  • "s3_uri": "string",
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "string",
  • "download_url": "string"
}

List Raw Files

List raw files stored for a workroom.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Source Urn (string) or Source Urn (null) (Source Urn)

Filter by source URN

Job Id (string) or Job Id (null) (Job Id)

Filter by pipeline job ID

Connector Id (string) or Connector Id (null) (Connector Id)

Filter to RawFiles ingested via a single connector instance (matches the connector_id segment of the source URN: urn:kamiwaza:context-source:<provider>:<connector_id>:...).

limit
integer (Limit) [ 1 .. 200 ]
Default: 50
offset
integer (Offset) >= 0
Default: 0
include_markings
boolean (Include Markings)
Default: false

When true, each row includes markings: list[str] aggregated per source from DDE document metadata (with connector default as fallback). Default-off preserves the existing call shape for callers that do not need markings. See system design §4.2.13.

header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "count": 0
}

Get Raw File

Get one raw-file metadata record by ID and workroom scope.

Authorizations:
BearerAuthOAuth2Login
path Parameters
file_id
required
string <uuid> (File Id)
query Parameters
include_download_url
boolean (Include Download Url)
Default: false

Include a pre-signed download URL when S3 metadata exists

Expires Seconds (integer) or Expires Seconds (null) (Expires Seconds)

Override pre-signed URL TTL in seconds

header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "source_urn": "string",
  • "filename": "string",
  • "content_type": "string",
  • "size_bytes": 0,
  • "checksum_sha256": "string",
  • "source_kind": "string",
  • "source_ref": { },
  • "s3_uri": "string",
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "string",
  • "download_url": "string"
}

Update Raw File

Update the content of a plain-text raw file (C13).

Edit access: any ContextWriter member of the workroom (no author-only gate). See system design v0.1.4 §3.8.5 + spikes/t1.1-c13-verb-shape.md for the locked contract.

Authorizations:
BearerAuthOAuth2Login
path Parameters
file_id
required
string <uuid> (File Id)
header Parameters
If-Match (string) or If-Match (null) (If-Match)

Optional concurrency-control token (the file's updated_at ISO-8601 string from a previous response). If provided and stale, returns 409 with the current token in the response detail.

X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Request Body schema: application/json
required
content
required
string (Content) <= 65535 characters

Replacement content for the raw file. Must be non-empty after .strip() and must not exceed RAW_FILE_MAX_EDIT_BYTES (65535 bytes) when UTF-8 encoded — see object_storage_service for the canonical byte-level constant. Pydantic enforces a character cap of 65535 here; the route enforces the exact UTF-8-byte cap after encoding.

Responses

Request samples

Content type
application/json
{
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "source_urn": "string",
  • "filename": "string",
  • "content_type": "string",
  • "size_bytes": 0,
  • "checksum_sha256": "string",
  • "source_kind": "string",
  • "source_ref": { },
  • "s3_uri": "string",
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "string",
  • "download_url": "string"
}

documents

Get Document Download Url

Get a presigned download URL for an original document.

Looks up the document by source URN in the source tracking database, then generates a presigned S3 URL for download.

Requires S3 storage to be enabled.

Authorizations:
BearerAuthOAuth2Login
path Parameters
source_urn
required
string (Source Urn)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "download_url": "string",
  • "filename": "string",
  • "content_hash": "string",
  • "source_urn": "string"
}

download

Download Raw File

Raw-file detail with a browser-reachable (public) presigned download URL.

Authorizations:
BearerAuthOAuth2Login
path Parameters
file_id
required
string <uuid> (File Id)
query Parameters
Expires Seconds (integer) or Expires Seconds (null) (Expires Seconds)

Override pre-signed URL TTL in seconds

header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f",
  • "source_urn": "string",
  • "filename": "string",
  • "content_type": "string",
  • "size_bytes": 0,
  • "checksum_sha256": "string",
  • "source_kind": "string",
  • "source_ref": { },
  • "s3_uri": "string",
  • "metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "string",
  • "download_url": "string"
}

Download Document

Original-document browser-reachable (public) presigned download URL.

Authorizations:
BearerAuthOAuth2Login
path Parameters
source_urn
required
string (Source Urn)
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "download_url": "string",
  • "filename": "string",
  • "content_hash": "string",
  • "source_urn": "string"
}

embedding-model

Set Embedding Model

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
group_id
required
string (Group Id) [ 1 .. 255 ] characters
Embedding Deployment Id (string) or Embedding Deployment Id (null) (Embedding Deployment Id)

Deployment to bind for this group_id. Pass null to clear any existing override and let auto-selection take over.

force
boolean (Force)
Default: false

Required when the override would change vector dimensions and thereby invalidate stored vectors. With force=true the server schedules a re-embedding job.

Responses

Request samples

Content type
application/json
{
  • "group_id": "string",
  • "embedding_deployment_id": "9bc4a55e-a75a-44ac-a151-591903486d14",
  • "force": false
}

Response samples

Content type
application/json
{
  • "group_id": "string",
  • "embedding_deployment_id": "9bc4a55e-a75a-44ac-a151-591903486d14",
  • "embedding_model_name": "string",
  • "embedding_dimensions": 0,
  • "source": "override",
  • "healthy": true,
  • "last_verified_at": "2019-08-24T14:15:22Z",
  • "first_used_at": "2019-08-24T14:15:22Z"
}

Get Embedding Model

Authorizations:
BearerAuthOAuth2Login
query Parameters
group_id
required
string (Group Id) [ 1 .. 255 ] characters
header Parameters
X-Workroom-Id (string) or X-Workroom-Id (null) (X-Workroom-Id)

Workroom ID for isolation

Responses

Response samples

Content type
application/json
{
  • "group_id": "string",
  • "embedding_deployment_id": "9bc4a55e-a75a-44ac-a151-591903486d14",
  • "embedding_model_name": "string",
  • "embedding_dimensions": 0,
  • "source": "override",
  • "healthy": true,
  • "last_verified_at": "2019-08-24T14:15:22Z",
  • "first_used_at": "2019-08-24T14:15:22Z"
}

news

Get News Quadrants

Get the structured news content in quadrant format.

Returns: NewsResponse: Object containing quadrant-structured news data

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "categories": [
    ],
  • "items": [
    ],
  • "quadrants": {
    }
}

Get News Quadrants

Get the structured news content in quadrant format.

Returns: NewsResponse: Object containing quadrant-structured news data

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "categories": [
    ],
  • "items": [
    ],
  • "quadrants": {
    }
}

Get Latest News

Get the latest news content from the Kamiwaza news API. Legacy endpoint for backward compatibility.

Returns: NewsContent: Object containing news content or error message

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "content": "## Latest Kamiwaza Updates\n\n### Kamiwaza 2.2.0 Released\n*January 10, 2025*\n\nMajor update with improved model deployment, enhanced UI, and better performance monitoring.\n\n### New Model Support\n*January 5, 2025*\n\nAdded support for **Llama 3.3**, **DeepSeek V3**, and **Qwen 2.5** series models.",
  • "timestamp": "2025-01-15T00:00:00Z"
}

Get Latest News

Get the latest news content from the Kamiwaza news API. Legacy endpoint for backward compatibility.

Returns: NewsContent: Object containing news content or error message

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "content": "## Latest Kamiwaza Updates\n\n### Kamiwaza 2.2.0 Released\n*January 10, 2025*\n\nMajor update with improved model deployment, enhanced UI, and better performance monitoring.\n\n### New Model Support\n*January 5, 2025*\n\nAdded support for **Llama 3.3**, **DeepSeek V3**, and **Qwen 2.5** series models.",
  • "timestamp": "2025-01-15T00:00:00Z"
}

logger

List All Deployment Logs

List all deployment logs across all services. This is the main endpoint for the unified logs viewer UI.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "logs": [
    ],
  • "total_count": 0,
  • "orphaned_count": 0
}

List Logs By Type

List all logs for a specific deployment type. Uses filesystem directory structure for filtering.

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_type
required
string (DeploymentType)
Enum: "vllm" "llamacpp" "mlx" "diffusion" "ampere" "whispercpp" "app_garden" "tool_shed" "unknown"

Type of deployment

Responses

Response samples

Content type
application/json
{
  • "logs": [
    ],
  • "total_count": 0,
  • "orphaned_count": 0
}

List Orphaned Logs

List all orphaned log files (deployments that no longer exist).

Orphaned log files do not have a deployment row available for owner or workroom verification, so this route is admin-only.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "logs": [
    ],
  • "total_count": 0,
  • "orphaned_count": 0
}

Get Deployment Log Content

Get the content of a specific deployment log.

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_type
required
string (DeploymentType)
Enum: "vllm" "llamacpp" "mlx" "diffusion" "ampere" "whispercpp" "app_garden" "tool_shed" "unknown"

Type of deployment

deployment_id
required
string <uuid> (Deployment Id)

Deployment ID

Responses

Response samples

Content type
application/json
{
  • "deployment_id": "string",
  • "deployment_type": "vllm",
  • "file_path": "string",
  • "logs": [
    ],
  • "total_lines": 0,
  • "is_compressed": false,
  • "patterns_detected": {
    },
  • "capture_active": false
}

Delete Deployment Log

Delete a specific deployment log file.

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_type
required
string (DeploymentType)
Enum: "vllm" "llamacpp" "mlx" "diffusion" "ampere" "whispercpp" "app_garden" "tool_shed" "unknown"

Type of deployment

deployment_id
required
string (Deployment Id)

Deployment ID

query Parameters
confirm
boolean (Confirm)
Default: false

Confirm deletion

Responses

Response samples

Content type
application/json
{
  • "deleted": true,
  • "message": "string",
  • "files_removed": [
    ]
}

Analyze Deployment Patterns

Analyze deployment logs for error patterns.

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_type
required
string (DeploymentType)
Enum: "vllm" "llamacpp" "mlx" "diffusion" "ampere" "whispercpp" "app_garden" "tool_shed" "unknown"

Type of deployment

deployment_id
required
string <uuid> (Deployment Id)

Deployment ID

Responses

Response samples

Content type
application/json
{
  • "deployment_id": "string",
  • "deployment_type": "vllm",
  • "patterns_detected": {
    },
  • "failure_lines": [
    ],
  • "analysis_timestamp": "2019-08-24T14:15:22Z",
  • "total_errors_found": 0
}

Get Log Statistics

Get storage statistics for all logs.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "total_logs": 0,
  • "total_size_bytes": 0,
  • "orphaned_count": 0,
  • "by_type": {
    },
  • "storage_path": "string",
  • "last_updated": "2019-08-24T14:15:22Z"
}

Cleanup Old Logs

Clean up old log files.

Authorizations:
BearerAuthOAuth2Login
query Parameters
days_old
integer (Days Old)
Default: 30

Delete logs older than this many days

DeploymentType (string) or Deployment Type (null) (Deployment Type)

Filter by deployment type

dry_run
boolean (Dry Run)
Default: true

If true, only show what would be deleted

Responses

Response samples

Content type
application/json
null

Get Deployment Logs Legacy

Legacy endpoint for backward compatibility with existing UI. Get container logs for a specific deployment.

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)

Responses

Response samples

Content type
application/json
{
  • "deployment_id": "string",
  • "deployment_type": "vllm",
  • "file_path": "string",
  • "logs": [
    ],
  • "total_lines": 0,
  • "is_compressed": false,
  • "patterns_detected": {
    },
  • "capture_active": false
}

Get Deployment Log Patterns Legacy

Legacy endpoint for backward compatibility. Analyze container logs for failure patterns.

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)

Responses

Response samples

Content type
application/json
{
  • "deployment_id": "string",
  • "deployment_type": "vllm",
  • "patterns_detected": {
    },
  • "failure_lines": [
    ],
  • "analysis_timestamp": "2019-08-24T14:15:22Z",
  • "total_errors_found": 0
}

List Engine Logs Legacy

Legacy endpoint for backward compatibility. List available container logs for a specific engine type.

Authorizations:
BearerAuthOAuth2Login
path Parameters
engine_type
required
string (Engine Type)

Responses

Response samples

Content type
application/json
{
  • "logs": [
    ],
  • "total_count": 0,
  • "orphaned_count": 0
}

apps

Get Ephemeral Forced Config

Get whether ephemeral mode is forced for all app deployments.

When KAMIWAZA_EPHEMERAL_EXTENSIONS=true, all deployments are forced to be ephemeral and the user cannot override this in the UI.

Returns: EphemeralConfigResponse: Whether ephemeral mode is forced.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "ephemeral_forced": true
}

Deploy App

Deploy a new application.

.. deprecated:: Use POST /extensions API instead. This endpoint will be removed in a future release.

Args: create_app_request (CreateAppDeployment): The deployment request containing app configuration. audit_ctx: Automatically extracted audit context for logging

Returns: AppDeployment: The created app deployment details.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name)

Name of the app deployment

Template Id (string) or Template Id (null) (Template Id)

The UUID of the app template to use

min_copies
integer (Min Copies)
Default: 1

Minimum number of copies to maintain

starting_copies
integer (Starting Copies)
Default: 1

Number of copies to start with

Max Copies (integer) or Max Copies (null) (Max Copies)

Maximum number of copies allowed

Serve Path (string) or Serve Path (null) (Serve Path)

Optional path prefix for the deployment

lb_port
integer (Lb Port)
Default: 0

Port on which the load balancer is listening

Array of Port Mappings (objects) or Port Mappings (null) (Port Mappings)

Optional explicit port mappings

Runtime Resources Id (string) or Runtime Resources Id (null) (Runtime Resources Id)

Optional ID of the resource specification (e.g., CPU, memory limits) for this deployment

Env Vars (object) or Env Vars (null) (Env Vars)

Environment variables to pass to the app container

Is Ephemeral Session (boolean) or Is Ephemeral Session (null) (Is Ephemeral Session)

Override the default app session policy. True => purge on logout, False => persistent.

Preferred Model Type (string) or Preferred Model Type (null) (Preferred Model Type)

Preferred model type: any, large, reasoning, fast, vl. If None, skips model discovery.

fail_if_model_type_unavailable
boolean (Fail If Model Type Unavailable)
Default: false

Fail deployment if preferred model type unavailable

Preferred Model Name (string) or Preferred Model Name (null) (Preferred Model Name)

Specific model name to prefer (substring match)

fail_if_model_name_unavailable
boolean (Fail If Model Name Unavailable)
Default: false

Fail deployment if preferred model name not found

Responses

Request samples

Content type
application/json
{
  • "env_vars": {
    },
  • "lb_port": 0,
  • "max_copies": 2,
  • "min_copies": 1,
  • "name": "my-app-deployment",
  • "serve_path": "/runtime/apps/my-app",
  • "starting_copies": 1,
  • "template_id": "33333333-3333-3333-3333-333333333333"
}

Response samples

Content type
application/json
{
  • "env_vars": {
    },
  • "lb_port": 0,
  • "max_copies": 2,
  • "min_copies": 1,
  • "name": "my-app-deployment",
  • "serve_path": "/runtime/apps/my-app",
  • "starting_copies": 1,
  • "template_id": "33333333-3333-3333-3333-333333333333"
}

List Deployments

List app deployments, optionally filtered by template type and workroom.

Returns: List[AppDeployment]: A list of matching app deployments.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Template Type (string) or Template Type (null) (Template Type)

Filter by template type: app, tool, or service. Defaults to 'app' (excludes tools and services).

Workroom Id (string) or Workroom Id (null) (Workroom Id)

Filter by workroom ID. Pass 'all' to list across all workrooms.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Deployment

Get details of a specific app deployment.

Args: deployment_id (UUID): The ID of the deployment to retrieve.

Returns: AppDeployment: The deployment details.

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)

Responses

Response samples

Content type
application/json
{
  • "env_vars": {
    },
  • "lb_port": 0,
  • "max_copies": 2,
  • "min_copies": 1,
  • "name": "my-app-deployment",
  • "serve_path": "/runtime/apps/my-app",
  • "starting_copies": 1,
  • "template_id": "33333333-3333-3333-3333-333333333333"
}

Stop Deployment

Stop an app deployment.

Args: deployment_id (UUID): The ID of the deployment to stop. audit_ctx: Automatically extracted audit context for logging

Returns: bool: True if successfully stopped, False otherwise.

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)

Responses

Response samples

Content type
application/json
true

Purge Deployment

Stop and completely remove an app deployment.

Requires authentication and ownership verification. Users can only purge their own deployments unless they have admin role.

Admin cross-user purges are rate limited to prevent abuse and ensure proper audit trails are maintained.

Args: deployment_id (UUID): The ID of the deployment to purge. current_user: Authenticated user (injected by dependency)

Returns: bool: True if successfully purged.

Raises: HTTPException: 403 if user doesn't own the deployment and isn't admin HTTPException: 404 if deployment doesn't exist HTTPException: 429 if admin rate limit exceeded HTTPException: 500 if purge operation fails

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)

Responses

Response samples

Content type
application/json
true

App Session Heartbeat

Record a heartbeat for an authenticated app session token.

Authorizations:
OAuth2LoginBearerAuth

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "deployment_id": "6ef0ac85-9892-4664-a2a5-58bf2af5a8a6"
}

End App Session

End an authenticated app session token and purge the deployment.

Authorizations:
OAuth2LoginBearerAuth
Request Body schema: application/json
Reason (string) or Reason (null) (Reason)

Optional reason for ending the session, used for audit logging.

Any of
string (Reason)

Optional reason for ending the session, used for audit logging.

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "deployment_id": "6ef0ac85-9892-4664-a2a5-58bf2af5a8a6"
}

List Instances

List all app instances, optionally filtered by deployment.

Args: deployment_id (Optional[UUID]): Optional deployment ID to filter instances.

Returns: List[AppInstance]: List of app instances.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Deployment Id (string) or Deployment Id (null) (Deployment Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Instance

Get details of a specific app instance.

Args: instance_id (UUID): The ID of the instance to retrieve.

Returns: AppInstance: The instance details.

Authorizations:
BearerAuthOAuth2Login
path Parameters
instance_id
required
string <uuid> (Instance Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "deployment_id": "6ef0ac85-9892-4664-a2a5-58bf2af5a8a6",
  • "deployed_at": "2019-08-24T14:15:22Z",
  • "container_id": "string",
  • "node_id": "6e0bdcac-9717-4a6f-972e-97489dffeb0c",
  • "host_name": "string",
  • "listen_port": 0,
  • "status": "UNINITIALIZED"
}

Get Deployment Status

Get the status of a specific app deployment.

Args: deployment_id (UUID): The ID of the deployment.

Returns: str: The current status of the deployment.

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)

Responses

Response samples

Content type
application/json
"string"

app_templates

Create App Template

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name)

Template display name

Version (string) or Version (null) (Version)

Semver string, default 1.0.0

source_type
required
string (TemplateSource)
Enum: "kamiwaza" "user_repo" "public"

Origin of the template: kamiwaza, user_repo, or public

visibility
string (TemplateVisibility)
Default: "private"
Enum: "private" "team" "public"

Access visibility: private, team, or public

compose_yml
required
string (Compose Yml)

Raw docker-compose YAML content

risk_tier
integer (RiskTier)
Default: 0
Enum: 0 1 2

Risk tier: 0 (guided), 1 (scanned), or 2 (break_glass)

validate_containers
boolean (Validate Containers)
Default: false

If true, attempt to pull / inspect referenced images on create

Owner Id (string) or Owner Id (string) or Owner Id (null) (Owner Id)

User ID of template owner (injected by API layer)

Env Defaults (object) or Env Defaults (null) (Env Defaults)

Default environment variables for the template

Env Metadata (object) or Env Metadata (null) (Env Metadata)

UI metadata for env vars (type, options, label, description). Keys correspond to env_defaults keys. Supports type='select' with options list.

TemplateType (string) or null

Extension type: app, tool, or service. Auto-resolved from name if not set.

Display Name (string) or Display Name (null) (Display Name)

Human-readable display name (e.g., 'Kamiwaza DDE' instead of 'tool-kamiwaza-dde')

Description (string) or Description (null) (Description)

Template description

Category (string) or Category (null) (Category)

Template category (e.g., internet_data, model_tools)

Array of Tags (strings) or Tags (null) (Tags)

List of tags for categorization and search

Author (string) or Author (null) (Author)

Template author/organization

License (string) or License (null) (License)

Software license (e.g., MIT, Apache-2.0)

Homepage (string) or Homepage (null) (Homepage)

Homepage/repository URL

Image (string) or Image (null) (Image)

Docker image reference

Array of Capabilities (strings) or Capabilities (null) (Capabilities)

List of capabilities provided by this template

Array of Required Env Vars (strings) or Required Env Vars (null) (Required Env Vars)

List of required environment variables

Preferred Model Type (string) or Preferred Model Type (null) (Preferred Model Type)

Preferred model type: None (no model), any, large, reasoning, fast, vl

fail_if_model_type_unavailable
boolean (Fail If Model Type Unavailable)
Default: false

Fail deployment if preferred model type unavailable

Preferred Model Name (string) or Preferred Model Name (null) (Preferred Model Name)

Specific model name to prefer (substring match)

fail_if_model_name_unavailable
boolean (Fail If Model Name Unavailable)
Default: false

Fail deployment if preferred model name not found

Preview Image (string) or Preview Image (null) (Preview Image)

Preview image path (e.g., images/my-app-preview.png) or resolved serving path

Preview Image Data (string) or Preview Image Data (null) (Preview Image Data)

Base64-encoded preview image data (used during push, not persisted)

Kamiwaza Version (string) or Kamiwaza Version (null) (Kamiwaza Version)

Kamiwaza version constraint (e.g., '>=0.7.0', '>=0.7.0,<0.9.0', '*')

Strip Path Prefix (boolean) or Strip Path Prefix (null) (Strip Path Prefix)

Whether Traefik should strip the path prefix before forwarding. Defaults to True for tools, False for apps and services.

Responses

Request samples

Content type
application/json
{
  • "compose_yml": "services:\n app:\n image: myapp:latest\n ports:\n - '8080'\n",
  • "name": "my-extension",
  • "source_type": "kamiwaza",
  • "template_type": "app"
}

Response samples

Content type
application/json
{
  • "compose_yml": "services:\n app:\n image: myapp:latest\n ports:\n - '8080'\n",
  • "name": "my-extension",
  • "source_type": "kamiwaza",
  • "template_type": "app"
}

List App Templates

Authorizations:
BearerAuthOAuth2Login
query Parameters
Template Type (string) or Template Type (null) (Template Type)

Filter by template type: app, tool, or service. Defaults to 'app' (excludes tools and services).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get App Template

Authorizations:
BearerAuthOAuth2Login
path Parameters
template_id
required
string <uuid> (Template Id)

Responses

Response samples

Content type
application/json
{
  • "compose_yml": "services:\n app:\n image: myapp:latest\n ports:\n - '8080'\n",
  • "name": "my-extension",
  • "source_type": "kamiwaza",
  • "template_type": "app"
}

Update Template

Update a template using API-provided payload data.

Authorizations:
BearerAuthOAuth2Login
path Parameters
template_id
required
string <uuid> (Template Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)

Template display name

Version (string) or Version (null) (Version)

Semver string, default 1.0.0

TemplateSource (string) or null

Origin of the template: kamiwaza, user_repo, or public

TemplateVisibility (string) or null

Access visibility: private, team, or public

Compose Yml (string) or Compose Yml (null) (Compose Yml)

Raw docker-compose YAML content

RiskTier (integer) or null

Risk tier: 0 (guided), 1 (scanned), or 2 (break_glass)

Validate Containers (boolean) or Validate Containers (null) (Validate Containers)

If true, attempt to pull / inspect referenced images on update

Env Defaults (object) or Env Defaults (null) (Env Defaults)

Default environment variables for the template

Env Metadata (object) or Env Metadata (null) (Env Metadata)

UI metadata for env vars (type, options, label, description). Keys correspond to env_defaults keys. Supports type='select' with options list.

TemplateType (string) or null

Extension type: app, tool, or service

Display Name (string) or Display Name (null) (Display Name)

Human-readable display name

Description (string) or Description (null) (Description)

Template description

Category (string) or Category (null) (Category)

Template category

Array of Tags (strings) or Tags (null) (Tags)

List of tags

Author (string) or Author (null) (Author)

Template author/organization

License (string) or License (null) (License)

Software license

Homepage (string) or Homepage (null) (Homepage)

Homepage/repository URL

Image (string) or Image (null) (Image)

Docker image reference

Array of Capabilities (strings) or Capabilities (null) (Capabilities)

Template capabilities

Array of Required Env Vars (strings) or Required Env Vars (null) (Required Env Vars)

List of required environment variables

Preferred Model Type (string) or Preferred Model Type (null) (Preferred Model Type)

Preferred model type: any, large, reasoning, fast, vl

Fail If Model Type Unavailable (boolean) or Fail If Model Type Unavailable (null) (Fail If Model Type Unavailable)

Fail deployment if preferred model type unavailable

Preferred Model Name (string) or Preferred Model Name (null) (Preferred Model Name)

Specific model name to prefer (substring match)

Fail If Model Name Unavailable (boolean) or Fail If Model Name Unavailable (null) (Fail If Model Name Unavailable)

Fail deployment if preferred model name not found

Preview Image (string) or Preview Image (null) (Preview Image)

Preview image path (e.g., images/my-app-preview.png) or resolved serving path

Preview Image Data (string) or Preview Image Data (null) (Preview Image Data)

Base64-encoded preview image data (used during push, not persisted)

Kamiwaza Version (string) or Kamiwaza Version (null) (Kamiwaza Version)

Kamiwaza version constraint

Strip Path Prefix (boolean) or Strip Path Prefix (null) (Strip Path Prefix)

Whether Traefik should strip the path prefix before forwarding

Responses

Request samples

Content type
application/json
{
  • "name": "my-extension-v2",
  • "template_type": "tool",
  • "version": "2.0.0"
}

Response samples

Content type
application/json
{
  • "compose_yml": "services:\n app:\n image: myapp:latest\n ports:\n - '8080'\n",
  • "name": "my-extension",
  • "source_type": "kamiwaza",
  • "template_type": "app"
}

Delete App Template

Delete an app template.

Authorizations:
BearerAuthOAuth2Login
path Parameters
template_id
required
string <uuid> (Template Id)

Responses

Response samples

Content type
application/json
null

Get Garden Status

Get status of garden apps - database vs remote catalog.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{ }

Import New Remote Apps

Import new remote app templates from info.kamiwaza.ai.

Args: current_user: Authenticated user (injected) audit_ctx: Audit context for logging (injected) sync_request: Optional filter for specific template names stage: Optional stage override (LOCAL/DEV/STAGE/PROD) for support use

Returns: Import results including counts and any errors

Raises: HTTPException: On validation errors or import failures

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
Array of Names (strings) or Names (null) (Names)

Specific template names to sync. If None, syncs all missing templates.

Any of
Array
string

Responses

Request samples

Content type
application/json
{
  • "names": [
    ]
}

Response samples

Content type
application/json
null

Put Catalog Overlay

Shadow a catalog template with a local dev build (ENG-6802).

Written by kz-ext dev so new workrooms launch the in-development build. The shadow survives remote catalog syncs until removed via DELETE.

Auth parity with the extension deploy surface (create_extension / patch_extension): anyone who can hot-swap the shared dev instance via kz-ext dev can already affect what every user sees, and the issue's semantics require the overlay write to work for whoever runs the dev loop. Writes are audit-logged with actor attribution; shadowing is restricted to Kamiwaza-sourced templates and fully reversible.

Authorizations:
BearerAuthOAuth2Login
path Parameters
name
required
string (Name) <= 120 characters
Request Body schema: application/json
required
version
required
string (Version) <= 40 characters

Shadow version, e.g. 0.4.0-dev.feat-x.f9b70f6

compose_yml
required
string (Compose Yml)

Transformed docker-compose YAML

Env Defaults (object) or Env Defaults (null) (Env Defaults)

Default environment variables

Env Metadata (object) or Env Metadata (null) (Env Metadata)

UI metadata for env vars

TemplateType (string) or null

Extension type: app, tool, or service

Display Name (string) or Display Name (null) (Display Name)

Human-readable name

Description (string) or Description (null) (Description)

Template description

Category (string) or Category (null) (Category)

Template category

Array of Tags (strings) or Tags (null) (Tags)

Tags for search

Author (string) or Author (null) (Author)

Template author/organization

License (string) or License (null) (License)

Software license

Homepage (string) or Homepage (null) (Homepage)

Homepage/repository URL

Image (string) or Image (null) (Image)

Docker image reference

Array of Capabilities (strings) or Capabilities (null) (Capabilities)

Capabilities provided by this template

Array of Required Env Vars (strings) or Required Env Vars (null) (Required Env Vars)

Required environment variables

Kamiwaza Version (string) or Kamiwaza Version (null) (Kamiwaza Version)

Kamiwaza version constraint

Strip Path Prefix (boolean) or Strip Path Prefix (null) (Strip Path Prefix)

Whether Traefik strips the path prefix

Preferred Model Type (string) or Preferred Model Type (null) (Preferred Model Type)

Preferred model type

Fail If Model Type Unavailable (boolean) or Fail If Model Type Unavailable (null) (Fail If Model Type Unavailable)

Fail deployment if preferred model type unavailable

Preferred Model Name (string) or Preferred Model Name (null) (Preferred Model Name)

Specific model name to prefer

Fail If Model Name Unavailable (boolean) or Fail If Model Name Unavailable (null) (Fail If Model Name Unavailable)

Fail deployment if preferred model name not found

object (CatalogOverlayShadowMeta)

Provenance of the dev build

Responses

Request samples

Content type
application/json
{
  • "version": "string",
  • "compose_yml": "string",
  • "env_defaults": {
    },
  • "env_metadata": { },
  • "template_type": "app",
  • "display_name": "string",
  • "description": "string",
  • "category": "string",
  • "tags": [
    ],
  • "author": "string",
  • "license": "string",
  • "homepage": "string",
  • "image": "string",
  • "capabilities": [
    ],
  • "required_env_vars": [
    ],
  • "kamiwaza_version": "string",
  • "strip_path_prefix": true,
  • "preferred_model_type": "string",
  • "fail_if_model_type_unavailable": true,
  • "preferred_model_name": "string",
  • "fail_if_model_name_unavailable": true,
  • "shadow": {
    }
}

Response samples

Content type
application/json
{
  • "shadow": {
    },
  • "template_created": true,
  • "running_deployments": [
    ]
}

Delete Catalog Overlay

Remove a local dev shadow, restoring the upstream catalog template.

Auth parity with put_catalog_overlay — unload is the less-privileged direction (it restores upstream content).

Authorizations:
BearerAuthOAuth2Login
path Parameters
name
required
string (Name) <= 120 characters

Responses

Response samples

Content type
application/json
{
  • "template_name": "string",
  • "restored_version": "string",
  • "template_removed": true
}

List Catalog Overlays

List active local dev shadows (consumed by kz-ext status).

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Remote Template Status

Get status of remote templates - new available, updates available, etc.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{ }

List Remote Apps

List available remote app templates.

Authorizations:
BearerAuthOAuth2Login
query Parameters
force_refresh
boolean (Force Refresh)
Default: false

Responses

Response samples

Content type
application/json
[
  • { }
]

Import Garden Apps

Import missing garden apps as templates.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
null

Get Image Status

Check if images for a template have been pulled.

Authorizations:
BearerAuthOAuth2Login
path Parameters
template_id
required
string <uuid> (Template Id)

Responses

Response samples

Content type
application/json
null

Pull Template Images

Pull all images for a template.

Authorizations:
BearerAuthOAuth2Login
path Parameters
template_id
required
string <uuid> (Template Id)

Responses

Response samples

Content type
application/json
null

Tool Shed

Deploy Tool Server

Deploy a new Tool server from a Docker image.

This endpoint creates a new Tool deployment and returns a public HTTPS URL that can be used with any Tool-compatible client.

Args: request: Deployment configuration including Docker image and environment variables current_user: Authenticated user (injected)

Returns: ToolDeployment: Deployment details including the generated public URL

Raises: HTTPException: If deployment fails

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name)

Name for the Tool deployment

template_name
required
string (Template Name)

Name of the tool template to use

Env Vars (object) or Env Vars (null) (Env Vars)

Environment variables

min_copies
integer (Min Copies)
Default: 1

Minimum number of instances

max_copies
integer (Max Copies)
Default: 1

Maximum number of instances

Responses

Request samples

Content type
application/json
{
  • "env_vars": {
    },
  • "name": "my-math-tools",
  • "template_name": "tool-websearch"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "requested_at": "2019-08-24T14:15:22Z",
  • "deployed_at": "2019-08-24T14:15:22Z",
  • "status": "UNINITIALIZED",
  • "created_at": "2019-08-24T14:15:22Z",
  • "compose_yml": "string",
  • "min_copies": 1,
  • "max_copies": 0,
  • "env_vars": {
    },
  • "url": "string",
  • "deployment_type": "tool"
}

Deploy Tool Server

Deploy a new Tool server from a Docker image.

This endpoint creates a new Tool deployment and returns a public HTTPS URL that can be used with any Tool-compatible client.

Args: request: Deployment configuration including Docker image and environment variables current_user: Authenticated user (injected)

Returns: ToolDeployment: Deployment details including the generated public URL

Raises: HTTPException: If deployment fails

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name)

Name for the Tool deployment

template_name
required
string (Template Name)

Name of the tool template to use

Env Vars (object) or Env Vars (null) (Env Vars)

Environment variables

min_copies
integer (Min Copies)
Default: 1

Minimum number of instances

max_copies
integer (Max Copies)
Default: 1

Maximum number of instances

Responses

Request samples

Content type
application/json
{
  • "env_vars": {
    },
  • "name": "my-math-tools",
  • "template_name": "tool-websearch"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "requested_at": "2019-08-24T14:15:22Z",
  • "deployed_at": "2019-08-24T14:15:22Z",
  • "status": "UNINITIALIZED",
  • "created_at": "2019-08-24T14:15:22Z",
  • "compose_yml": "string",
  • "min_copies": 1,
  • "max_copies": 0,
  • "env_vars": {
    },
  • "url": "string",
  • "deployment_type": "tool"
}

Deploy From Template

Deploy a Tool server from a pre-built template.

This is a convenience endpoint that combines template lookup and deployment.

Args: template_name: Name of the template (e.g., "tool-websearch") name: Name for your deployment instance env_vars: Optional environment variables (e.g., API keys) current_user: Authenticated user (injected)

Returns: ToolDeployment: Deployment details including the generated public URL

Example: POST /tool/deploy-template/tool-websearch { "name": "my-search-tool", "env_vars": { "TAVILY_API_KEY": "your-api-key" } }

Authorizations:
BearerAuthOAuth2Login
path Parameters
template_name
required
string (Template Name)
Request Body schema: application/json
required
name
required
string (Name)

Name for your deployment instance

Env Vars (object) or Env Vars (null) (Env Vars)

Environment variables (e.g., API keys)

Responses

Request samples

Content type
application/json
{
  • "env_vars": {
    },
  • "name": "my-search-tool"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "requested_at": "2019-08-24T14:15:22Z",
  • "deployed_at": "2019-08-24T14:15:22Z",
  • "status": "UNINITIALIZED",
  • "created_at": "2019-08-24T14:15:22Z",
  • "compose_yml": "string",
  • "min_copies": 1,
  • "max_copies": 0,
  • "env_vars": {
    },
  • "url": "string",
  • "deployment_type": "tool"
}

Deploy From Template

Deploy a Tool server from a pre-built template.

This is a convenience endpoint that combines template lookup and deployment.

Args: template_name: Name of the template (e.g., "tool-websearch") name: Name for your deployment instance env_vars: Optional environment variables (e.g., API keys) current_user: Authenticated user (injected)

Returns: ToolDeployment: Deployment details including the generated public URL

Example: POST /tool/deploy-template/tool-websearch { "name": "my-search-tool", "env_vars": { "TAVILY_API_KEY": "your-api-key" } }

Authorizations:
BearerAuthOAuth2Login
path Parameters
template_name
required
string (Template Name)
Request Body schema: application/json
required
name
required
string (Name)

Name for your deployment instance

Env Vars (object) or Env Vars (null) (Env Vars)

Environment variables (e.g., API keys)

Responses

Request samples

Content type
application/json
{
  • "env_vars": {
    },
  • "name": "my-search-tool"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "requested_at": "2019-08-24T14:15:22Z",
  • "deployed_at": "2019-08-24T14:15:22Z",
  • "status": "UNINITIALIZED",
  • "created_at": "2019-08-24T14:15:22Z",
  • "compose_yml": "string",
  • "min_copies": 1,
  • "max_copies": 0,
  • "env_vars": {
    },
  • "url": "string",
  • "deployment_type": "tool"
}

List Tool Deployments

List all Tool deployments.

Returns a list of all active Tool server deployments with their public URLs.

Returns: List[ToolDeployment]: List of Tool deployments

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Tool Deployments

List all Tool deployments.

Returns a list of all active Tool server deployments with their public URLs.

Returns: List[ToolDeployment]: List of Tool deployments

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Tool Deployment

Get details of a specific Tool deployment.

Args: deployment_id: UUID of the deployment current_user: Authenticated user (injected)

Returns: ToolDeployment: Deployment details with URL

Raises: HTTPException: If deployment not found

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)

UUID of the tool deployment

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "requested_at": "2019-08-24T14:15:22Z",
  • "deployed_at": "2019-08-24T14:15:22Z",
  • "status": "UNINITIALIZED",
  • "created_at": "2019-08-24T14:15:22Z",
  • "compose_yml": "string",
  • "min_copies": 1,
  • "max_copies": 0,
  • "env_vars": {
    },
  • "url": "string",
  • "deployment_type": "tool"
}

Get Tool Deployment

Get details of a specific Tool deployment.

Args: deployment_id: UUID of the deployment current_user: Authenticated user (injected)

Returns: ToolDeployment: Deployment details with URL

Raises: HTTPException: If deployment not found

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)

UUID of the tool deployment

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "requested_at": "2019-08-24T14:15:22Z",
  • "deployed_at": "2019-08-24T14:15:22Z",
  • "status": "UNINITIALIZED",
  • "created_at": "2019-08-24T14:15:22Z",
  • "compose_yml": "string",
  • "min_copies": 1,
  • "max_copies": 0,
  • "env_vars": {
    },
  • "url": "string",
  • "deployment_type": "tool"
}

Stop Tool Deployment

Stop and remove a tool deployment.

This will terminate the tool server container(s) and clean up associated resources.

Args: deployment_id: UUID of the deployment to stop current_user: Authenticated user (injected)

Returns: dict: Success message

Raises: HTTPException: If deployment not found or stop fails

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)

UUID of the tool deployment to stop

Responses

Response samples

Content type
application/json
{ }

Stop Tool Deployment

Stop and remove a tool deployment.

This will terminate the tool server container(s) and clean up associated resources.

Args: deployment_id: UUID of the deployment to stop current_user: Authenticated user (injected)

Returns: dict: Success message

Raises: HTTPException: If deployment not found or stop fails

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)

UUID of the tool deployment to stop

Responses

Response samples

Content type
application/json
{ }

Discover Tool Servers

Discover available tool servers and their capabilities.

This endpoint returns information about all deployed tool servers, including their capabilities (when available).

Returns: ToolDiscovery: List of available tool servers

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "servers": [
    ],
  • "total": 1
}

Discover Tool Servers

Discover available tool servers and their capabilities.

This endpoint returns information about all deployed tool servers, including their capabilities (when available).

Returns: ToolDiscovery: List of available tool servers

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "servers": [
    ],
  • "total": 1
}

Check Tool Health

Check the health status of a tool deployment.

This endpoint performs a health check on the specified tool server to verify it's running and responding to the tool protocol.

Args: deployment_id: UUID of the deployment to check current_user: Authenticated user (injected)

Returns: ToolHealthCheck: Health status information

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)

UUID of the tool deployment

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "protocol_version": "string",
  • "last_checked": "2019-08-24T14:15:22Z",
  • "error": "string"
}

Check Tool Health

Check the health status of a tool deployment.

This endpoint performs a health check on the specified tool server to verify it's running and responding to the tool protocol.

Args: deployment_id: UUID of the deployment to check current_user: Authenticated user (injected)

Returns: ToolHealthCheck: Health status information

Authorizations:
BearerAuthOAuth2Login
path Parameters
deployment_id
required
string <uuid> (Deployment Id)

UUID of the tool deployment

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "protocol_version": "string",
  • "last_checked": "2019-08-24T14:15:22Z",
  • "error": "string"
}

List Available Templates

List available pre-built Tool templates.

Returns a list of templates that can be imported and deployed.

Returns: List[dict]: Available Tool templates

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
[
  • { }
]

List Available Templates

List available pre-built Tool templates.

Returns a list of templates that can be imported and deployed.

Returns: List[dict]: Available Tool templates

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
[
  • { }
]

List Tool Templates

List tool templates from database (already imported).

Returns only templates that have been imported into the database, filtered to show only tool templates (names starting with "tool-"). Transforms the data to include Tool-specific fields from env_defaults.

Returns: List[Dict]: Imported tool templates with Tool-specific fields

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
[
  • { }
]

List Tool Templates

List tool templates from database (already imported).

Returns only templates that have been imported into the database, filtered to show only tool templates (names starting with "tool-"). Transforms the data to include Tool-specific fields from env_defaults.

Returns: List[Dict]: Imported tool templates with Tool-specific fields

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
[
  • { }
]

Update Tool Template

Update an existing tool template (local changes, no remote fetch).

Authorizations:
BearerAuthOAuth2Login
path Parameters
template_id
required
string <uuid> (Template Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)

Template display name

Version (string) or Version (null) (Version)

Semver string, default 1.0.0

TemplateSource (string) or null

Origin of the template: kamiwaza, user_repo, or public

TemplateVisibility (string) or null

Access visibility: private, team, or public

Compose Yml (string) or Compose Yml (null) (Compose Yml)

Raw docker-compose YAML content

RiskTier (integer) or null

Risk tier: 0 (guided), 1 (scanned), or 2 (break_glass)

Validate Containers (boolean) or Validate Containers (null) (Validate Containers)

If true, attempt to pull / inspect referenced images on update

Env Defaults (object) or Env Defaults (null) (Env Defaults)

Default environment variables for the template

Env Metadata (object) or Env Metadata (null) (Env Metadata)

UI metadata for env vars (type, options, label, description). Keys correspond to env_defaults keys. Supports type='select' with options list.

TemplateType (string) or null

Extension type: app, tool, or service

Display Name (string) or Display Name (null) (Display Name)

Human-readable display name

Description (string) or Description (null) (Description)

Template description

Category (string) or Category (null) (Category)

Template category

Array of Tags (strings) or Tags (null) (Tags)

List of tags

Author (string) or Author (null) (Author)

Template author/organization

License (string) or License (null) (License)

Software license

Homepage (string) or Homepage (null) (Homepage)

Homepage/repository URL

Image (string) or Image (null) (Image)

Docker image reference

Array of Capabilities (strings) or Capabilities (null) (Capabilities)

Template capabilities

Array of Required Env Vars (strings) or Required Env Vars (null) (Required Env Vars)

List of required environment variables

Preferred Model Type (string) or Preferred Model Type (null) (Preferred Model Type)

Preferred model type: any, large, reasoning, fast, vl

Fail If Model Type Unavailable (boolean) or Fail If Model Type Unavailable (null) (Fail If Model Type Unavailable)

Fail deployment if preferred model type unavailable

Preferred Model Name (string) or Preferred Model Name (null) (Preferred Model Name)

Specific model name to prefer (substring match)

Fail If Model Name Unavailable (boolean) or Fail If Model Name Unavailable (null) (Fail If Model Name Unavailable)

Fail deployment if preferred model name not found

Preview Image (string) or Preview Image (null) (Preview Image)

Preview image path (e.g., images/my-app-preview.png) or resolved serving path

Preview Image Data (string) or Preview Image Data (null) (Preview Image Data)

Base64-encoded preview image data (used during push, not persisted)

Kamiwaza Version (string) or Kamiwaza Version (null) (Kamiwaza Version)

Kamiwaza version constraint

Strip Path Prefix (boolean) or Strip Path Prefix (null) (Strip Path Prefix)

Whether Traefik should strip the path prefix before forwarding

Responses

Request samples

Content type
application/json
{
  • "name": "my-extension-v2",
  • "template_type": "tool",
  • "version": "2.0.0"
}

Response samples

Content type
application/json
{
  • "compose_yml": "services:\n app:\n image: myapp:latest\n ports:\n - '8080'\n",
  • "name": "my-extension",
  • "source_type": "kamiwaza",
  • "template_type": "app"
}

Update Tool Template

Update an existing tool template (local changes, no remote fetch).

Authorizations:
BearerAuthOAuth2Login
path Parameters
template_id
required
string <uuid> (Template Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)

Template display name

Version (string) or Version (null) (Version)

Semver string, default 1.0.0

TemplateSource (string) or null

Origin of the template: kamiwaza, user_repo, or public

TemplateVisibility (string) or null

Access visibility: private, team, or public

Compose Yml (string) or Compose Yml (null) (Compose Yml)

Raw docker-compose YAML content

RiskTier (integer) or null

Risk tier: 0 (guided), 1 (scanned), or 2 (break_glass)

Validate Containers (boolean) or Validate Containers (null) (Validate Containers)

If true, attempt to pull / inspect referenced images on update

Env Defaults (object) or Env Defaults (null) (Env Defaults)

Default environment variables for the template

Env Metadata (object) or Env Metadata (null) (Env Metadata)

UI metadata for env vars (type, options, label, description). Keys correspond to env_defaults keys. Supports type='select' with options list.

TemplateType (string) or null

Extension type: app, tool, or service

Display Name (string) or Display Name (null) (Display Name)

Human-readable display name

Description (string) or Description (null) (Description)

Template description

Category (string) or Category (null) (Category)

Template category

Array of Tags (strings) or Tags (null) (Tags)

List of tags

Author (string) or Author (null) (Author)

Template author/organization

License (string) or License (null) (License)

Software license

Homepage (string) or Homepage (null) (Homepage)

Homepage/repository URL

Image (string) or Image (null) (Image)

Docker image reference

Array of Capabilities (strings) or Capabilities (null) (Capabilities)

Template capabilities

Array of Required Env Vars (strings) or Required Env Vars (null) (Required Env Vars)

List of required environment variables

Preferred Model Type (string) or Preferred Model Type (null) (Preferred Model Type)

Preferred model type: any, large, reasoning, fast, vl

Fail If Model Type Unavailable (boolean) or Fail If Model Type Unavailable (null) (Fail If Model Type Unavailable)

Fail deployment if preferred model type unavailable

Preferred Model Name (string) or Preferred Model Name (null) (Preferred Model Name)

Specific model name to prefer (substring match)

Fail If Model Name Unavailable (boolean) or Fail If Model Name Unavailable (null) (Fail If Model Name Unavailable)

Fail deployment if preferred model name not found

Preview Image (string) or Preview Image (null) (Preview Image)

Preview image path (e.g., images/my-app-preview.png) or resolved serving path

Preview Image Data (string) or Preview Image Data (null) (Preview Image Data)

Base64-encoded preview image data (used during push, not persisted)

Kamiwaza Version (string) or Kamiwaza Version (null) (Kamiwaza Version)

Kamiwaza version constraint

Strip Path Prefix (boolean) or Strip Path Prefix (null) (Strip Path Prefix)

Whether Traefik should strip the path prefix before forwarding

Responses

Request samples

Content type
application/json
{
  • "name": "my-extension-v2",
  • "template_type": "tool",
  • "version": "2.0.0"
}

Response samples

Content type
application/json
{
  • "compose_yml": "services:\n app:\n image: myapp:latest\n ports:\n - '8080'\n",
  • "name": "my-extension",
  • "source_type": "kamiwaza",
  • "template_type": "app"
}

Delete Tool Template

Delete a tool template (only if no active deployments exist).

Authorizations:
BearerAuthOAuth2Login
path Parameters
template_id
required
string <uuid> (Template Id)

Responses

Response samples

Content type
application/json
{ }

Delete Tool Template

Delete a tool template (only if no active deployments exist).

Authorizations:
BearerAuthOAuth2Login
path Parameters
template_id
required
string <uuid> (Template Id)

Responses

Response samples

Content type
application/json
{ }

Get Tool Garden Status

Get status of tool templates - database vs remote catalog.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{ }

Get Tool Garden Status

Get status of tool templates - database vs remote catalog.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{ }

Get Tool Remote Status

Get status of remote tool templates - new available, updates available, etc.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{ }

Get Tool Remote Status

Get status of remote tool templates - new available, updates available, etc.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{ }

Import New Remote Tools

Import new remote tool templates from info.kamiwaza.ai.

Args: sync_request: Optional filter for specific template names current_user: Authenticated user (injected) template_service: Template service (injected) stage: Optional stage override (LOCAL/DEV/STAGE/PROD) for support use catalog_version: Optional catalog version override (e.g. v2, v3)

Returns: Import results including counts and any errors

Raises: HTTPException: On validation errors or import failures

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
Array of Names (strings) or Names (null) (Names)

Specific template names to sync. If None, syncs all missing templates.

Any of
Array
string

Responses

Request samples

Content type
application/json
{
  • "names": [
    ]
}

Response samples

Content type
application/json
null

Import New Remote Tools

Import new remote tool templates from info.kamiwaza.ai.

Args: sync_request: Optional filter for specific template names current_user: Authenticated user (injected) template_service: Template service (injected) stage: Optional stage override (LOCAL/DEV/STAGE/PROD) for support use catalog_version: Optional catalog version override (e.g. v2, v3)

Returns: Import results including counts and any errors

Raises: HTTPException: On validation errors or import failures

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
Array of Names (strings) or Names (null) (Names)

Specific template names to sync. If None, syncs all missing templates.

Any of
Array
string

Responses

Request samples

Content type
application/json
{
  • "names": [
    ]
}

Response samples

Content type
application/json
null

List Remote Tools

List available remote tool templates.

Authorizations:
BearerAuthOAuth2Login
query Parameters
force_refresh
boolean (Force Refresh)
Default: false

Responses

Response samples

Content type
application/json
[
  • { }
]

List Remote Tools

List available remote tool templates.

Authorizations:
BearerAuthOAuth2Login
query Parameters
force_refresh
boolean (Force Refresh)
Default: false

Responses

Response samples

Content type
application/json
[
  • { }
]

Import Tool Garden Servers

Import tool templates from remote catalog (not from local file).

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
null

Import Tool Garden Servers

Import tool templates from remote catalog (not from local file).

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
null

extensions

List Extensions

List extensions visible to the current user.

Role gating is enforced by @guarded on ExtensionService.list_extensions. Admin/workroom scoping logic is in the API layer since it depends on the query parameter vs context.workroom_id distinction.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Workroom Id (string) or Workroom Id (null) (Workroom Id)

Filter by workroom ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Extension

Create a new KamiwazaExtension CR.

The response Extension.name is the concrete runtime CR name. Clients should persist that returned name for follow-up GET/DELETE because cross-workroom collisions may force a deterministic scoped name.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name)

Extension name (K8s DNS label)

type
required
string (Type)
Enum: "app" "tool" "service" "connector"

Extension type: 'app', 'tool', 'service', or 'connector'

version
required
string (Version)

Extension version (semver)

required
Array of objects (Services) non-empty

Service definitions

KamiwazaIntegrationSpec (object) or null

Kamiwaza platform integration settings

NetworkingSpec (object) or null

Networking and ingress configuration

SandboxSpec (object) or null

Sandbox runtime configuration

SecuritySpec (object) or null

Security classification and pod security

Workroom Id (string) or Workroom Id (null) (Workroom Id)

Workroom ID to associate with this extension

Annotations (object) or Annotations (null) (Annotations)

Optional client-supplied CR annotations. Only keys in the kamiwaza.ai/* namespace are accepted; the kamiwaza.io/* namespace is reserved for server-trusted annotations such as owner-user-id and workroom-id.

Responses

Request samples

Content type
application/json
{
  • "name": "my-app-abc12345",
  • "services": [
    ],
  • "type": "app",
  • "version": "1.0.0"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "template_name": "string",
  • "type": "string",
  • "version": "string",
  • "phase": "string",
  • "services": [
    ],
  • "endpoints": {
    },
  • "owner_user_id": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

List Workroom Scope Audit Findings

List legacy embedded runtimes that are null-scoped or Global-scoped.

Authorizations:
BearerAuthOAuth2Login
query Parameters
include_inactive
boolean (Include Inactive)
Default: false

Include stopped and failed legacy deployments in the report.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Status

Get rich deployment status for an extension.

Authorizations:
BearerAuthOAuth2Login
path Parameters
name
required
string (Name)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "phase": "string",
  • "url": "string",
  • "services": [
    ],
  • "rolling_update": false,
  • "events": [
    ]
}

Get Extension

Get a single extension by name.

Authorizations:
BearerAuthOAuth2Login
path Parameters
name
required
string (Name)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "template_name": "string",
  • "type": "string",
  • "version": "string",
  • "phase": "string",
  • "services": [
    ],
  • "endpoints": {
    },
  • "owner_user_id": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Patch Extension

Partially update an extension CR (image tag, replicas, env).

Authorizations:
BearerAuthOAuth2Login
path Parameters
name
required
string (Name)
Request Body schema: application/json
required
required
Array of objects (Services) non-empty

One or more service patches to apply

Annotations (object) or Annotations (null) (Annotations)

Optional client-supplied CR annotations to merge into existing metadata. Only keys in the kamiwaza.ai/* namespace are accepted.

Responses

Request samples

Content type
application/json
{
  • "services": [
    ],
  • "annotations": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "template_name": "string",
  • "type": "string",
  • "version": "string",
  • "phase": "string",
  • "services": [
    ],
  • "endpoints": {
    },
  • "owner_user_id": "string",
  • "workroom_id": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete Extension

Delete a KamiwazaExtension CR as an admin or owning user.

Authorizations:
BearerAuthOAuth2Login
path Parameters
name
required
string (Name)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Upgrade All Extensions

Re-render every template-driven deployed extension whose template digest differs from its running CR. Admin-only — enforced by AdminUser so FastAPI rejects non-admin callers before the route runs. Pod rolls are observed via the operator + k8s rolling update; this endpoint returns once each CR has either been PATCHed, recognized as up-to-date, or recorded with an error.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Names (string) or Names (null) (Names)

Comma-separated extension (CR) names to scope the upgrade.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ]
}

security

Get Public Config

Get public security configuration.

Returns configuration needed by the frontend to render:

  • Pre-login consent gate (if enabled)
  • Classification banners (if enabled)

This endpoint is public and does not require authentication.

Returns: SecurityConfigResponse: Configuration object containing: - consent_enabled: Whether consent gate is active - consent_content: HTML content for consent modal (if enabled) - banner_enabled: Whether classification banners are active - banner_text: Text to display in banners (if enabled) - banner_color: Hex color code for banners (if enabled)

Responses

Response samples

Content type
application/json
{
  • "consent_enabled": true,
  • "consent_content": "string",
  • "consent_button_label": "string",
  • "banner_enabled": true,
  • "banner_top_text": "string",
  • "banner_top_color": "string",
  • "banner_bottom_text": "string",
  • "banner_bottom_color": "string"
}

Get Public Config

Get public security configuration.

Returns configuration needed by the frontend to render:

  • Pre-login consent gate (if enabled)
  • Classification banners (if enabled)

This endpoint is public and does not require authentication.

Returns: SecurityConfigResponse: Configuration object containing: - consent_enabled: Whether consent gate is active - consent_content: HTML content for consent modal (if enabled) - banner_enabled: Whether classification banners are active - banner_text: Text to display in banners (if enabled) - banner_color: Hex color code for banners (if enabled)

Responses

Response samples

Content type
application/json
{
  • "consent_enabled": true,
  • "consent_content": "string",
  • "consent_button_label": "string",
  • "banner_enabled": true,
  • "banner_top_text": "string",
  • "banner_top_color": "string",
  • "banner_bottom_text": "string",
  • "banner_bottom_color": "string"
}

Accept Consent

Record consent acceptance.

Records that a user has accepted the consent terms. This is logged for audit purposes with client IP and user agent.

This endpoint is public as it must be accessible before login.

Args: request: FastAPI Request object used to extract client IP and user agent.

Returns: ConsentAcceptResponse: Confirmation object containing: - accepted: Boolean indicating consent was recorded - message: Status message

Responses

Response samples

Content type
application/json
{
  • "accepted": true,
  • "message": "string"
}

Accept Consent

Record consent acceptance.

Records that a user has accepted the consent terms. This is logged for audit purposes with client IP and user agent.

This endpoint is public as it must be accessible before login.

Args: request: FastAPI Request object used to extract client IP and user agent.

Returns: ConsentAcceptResponse: Confirmation object containing: - accepted: Boolean indicating consent was recorded - message: Status message

Responses

Response samples

Content type
application/json
{
  • "accepted": true,
  • "message": "string"
}

Get Embed Script

Get embeddable JavaScript bundle for classification banners and consent gate.

Returns a self-contained JavaScript file that apps can include to automatically display classification banners and enforce consent acceptance. Embedded apps that must preserve consent while suppressing classification banners can load /security/embed.js?classification_banners=0. The script:

  • Fetches security configuration from this API
  • Shows consent gate overlay if consent is required and not yet accepted
  • Injects CSS for banner and consent gate styling
  • Creates banner elements at top and bottom of page
  • Implements fail-closed behavior (shows consent gate on config failure)
  • Sanitizes HTML content to prevent XSS attacks

Usage in apps:

Security features:

  • Consent acceptance tracked via sessionStorage (per-session)
  • Consent acceptance logged to backend for audit purposes
  • Escape key disabled while consent gate is displayed
  • HTML content sanitized before rendering (strips dangerous tags/attributes)
  • Fail-closed: If config fetch fails, shows consent gate with Retry button

Returns: Response: JavaScript file with content-type application/javascript. Cached for 5 minutes via Cache-Control header.

Responses

Response samples

Content type
application/json
null

Get Embed Script

Get embeddable JavaScript bundle for classification banners and consent gate.

Returns a self-contained JavaScript file that apps can include to automatically display classification banners and enforce consent acceptance. Embedded apps that must preserve consent while suppressing classification banners can load /security/embed.js?classification_banners=0. The script:

  • Fetches security configuration from this API
  • Shows consent gate overlay if consent is required and not yet accepted
  • Injects CSS for banner and consent gate styling
  • Creates banner elements at top and bottom of page
  • Implements fail-closed behavior (shows consent gate on config failure)
  • Sanitizes HTML content to prevent XSS attacks

Usage in apps:

Security features:

  • Consent acceptance tracked via sessionStorage (per-session)
  • Consent acceptance logged to backend for audit purposes
  • Escape key disabled while consent gate is displayed
  • HTML content sanitized before rendering (strips dangerous tags/attributes)
  • Fail-closed: If config fetch fails, shows consent gate with Retry button

Returns: Response: JavaScript file with content-type application/javascript. Cached for 5 minutes via Cache-Control header.

Responses

Response samples

Content type
application/json
null

connectors

List Connectors

List all configured connector configs (admin only).

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List Connectors

List all configured connector configs (admin only).

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create Connector

Create a new connector configuration (admin only).

For a connector type that ships a deployable manifest, the workload is provisioned in the background after the row is created, so the connector reaches ready on its own (the card shows not_deployed -> deploying -> ready) instead of needing a separate sync.

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters
connector_type
required
string (Connector Type) non-empty

Connector type (a registered connector_type)

required
object (Config)

Provider-specific configuration

scopes
Array of strings (Scopes)

OAuth scopes

enabled
boolean (Enabled)
Default: true

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "connector_type": "string",
  • "config": { },
  • "scopes": [
    ],
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "connector_type": "string",
  • "enabled": true,
  • "scopes": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "redirect_uri": "string",
  • "icon": "string",
  • "status": "unknown",
  • "configured": false
}

Create Connector

Create a new connector configuration (admin only).

For a connector type that ships a deployable manifest, the workload is provisioned in the background after the row is created, so the connector reaches ready on its own (the card shows not_deployed -> deploying -> ready) instead of needing a separate sync.

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters
connector_type
required
string (Connector Type) non-empty

Connector type (a registered connector_type)

required
object (Config)

Provider-specific configuration

scopes
Array of strings (Scopes)

OAuth scopes

enabled
boolean (Enabled)
Default: true

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "connector_type": "string",
  • "config": { },
  • "scopes": [
    ],
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "connector_type": "string",
  • "enabled": true,
  • "scopes": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "redirect_uri": "string",
  • "icon": "string",
  • "status": "unknown",
  • "configured": false
}

Subscribe Connector

Subscribe a connector by manifest + endpoint (admin only).

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
required
object (Manifest)

The connector's self-describing manifest (ConnectorSpec.to_manifest()).

endpoint
required
string (Endpoint) [ 1 .. 2048 ] characters

HTTP/MCP endpoint where the connector is reached.

object (Config)

Provider-specific secret config (e.g. a service token), stored encrypted. Empty for connectors that need no stored credential.

scopes
Array of strings (Scopes)

Scopes this connector is granted. The mint enforces requested scope_subset ⊆ these; a service_token connector needs them to mint. May be empty for per-user OAuth connectors (scopes come per user).

Workload Principal Id (string) or Workload Principal Id (null) (Workload Principal Id)

Service-account principal permitted to mint per-user tokens for this connector. Bound at install; compared against the authenticated caller's principal at mint time. Null for connectors that never mint per-user tokens.

Responses

Request samples

Content type
application/json
{
  • "manifest": { },
  • "endpoint": "string",
  • "config": { },
  • "scopes": [
    ],
  • "workload_principal_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "connector_type": "string",
  • "enabled": true,
  • "scopes": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "redirect_uri": "string",
  • "icon": "string",
  • "status": "unknown",
  • "configured": false
}

Subscribe Connector

Subscribe a connector by manifest + endpoint (admin only).

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
required
object (Manifest)

The connector's self-describing manifest (ConnectorSpec.to_manifest()).

endpoint
required
string (Endpoint) [ 1 .. 2048 ] characters

HTTP/MCP endpoint where the connector is reached.

object (Config)

Provider-specific secret config (e.g. a service token), stored encrypted. Empty for connectors that need no stored credential.

scopes
Array of strings (Scopes)

Scopes this connector is granted. The mint enforces requested scope_subset ⊆ these; a service_token connector needs them to mint. May be empty for per-user OAuth connectors (scopes come per user).

Workload Principal Id (string) or Workload Principal Id (null) (Workload Principal Id)

Service-account principal permitted to mint per-user tokens for this connector. Bound at install; compared against the authenticated caller's principal at mint time. Null for connectors that never mint per-user tokens.

Responses

Request samples

Content type
application/json
{
  • "manifest": { },
  • "endpoint": "string",
  • "config": { },
  • "scopes": [
    ],
  • "workload_principal_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "connector_type": "string",
  • "enabled": true,
  • "scopes": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "redirect_uri": "string",
  • "icon": "string",
  • "status": "unknown",
  • "configured": false
}

List Connector Catalog

List connectors available to subscribe from the published catalog (admin).

Parity with the App Garden apps/tools catalog: connector manifests are fetched from the remote template catalog (or a file:// override) so an admin can browse and subscribe a connector without hand-supplying its manifest.

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List Connector Catalog

List connectors available to subscribe from the published catalog (admin).

Parity with the App Garden apps/tools catalog: connector manifests are fetched from the remote template catalog (or a file:// override) so an admin can browse and subscribe a connector without hand-supplying its manifest.

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Register Connector

Self-registration: register a connector already running at an endpoint (admin).

Core fetches the connector's self-describing manifest from GET {endpoint}/manifest and subscribes it with the supplied config.

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
endpoint
required
string (Endpoint) [ 1 .. 2048 ] characters
object (Config)
scopes
Array of strings (Scopes)
Workload Principal Id (string) or Workload Principal Id (null) (Workload Principal Id)

Responses

Request samples

Content type
application/json
{
  • "endpoint": "string",
  • "config": { },
  • "scopes": [
    ],
  • "workload_principal_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "connector_type": "string",
  • "enabled": true,
  • "scopes": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "redirect_uri": "string",
  • "icon": "string",
  • "status": "unknown",
  • "configured": false
}

Register Connector

Self-registration: register a connector already running at an endpoint (admin).

Core fetches the connector's self-describing manifest from GET {endpoint}/manifest and subscribes it with the supplied config.

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
endpoint
required
string (Endpoint) [ 1 .. 2048 ] characters
object (Config)
scopes
Array of strings (Scopes)
Workload Principal Id (string) or Workload Principal Id (null) (Workload Principal Id)

Responses

Request samples

Content type
application/json
{
  • "endpoint": "string",
  • "config": { },
  • "scopes": [
    ],
  • "workload_principal_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "connector_type": "string",
  • "enabled": true,
  • "scopes": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "redirect_uri": "string",
  • "icon": "string",
  • "status": "unknown",
  • "configured": false
}

List Available Connectors

List enabled connector metadata safe for user account connection flows.

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List Available Connectors

List enabled connector metadata safe for user account connection flows.

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List Connector Types

List registered connector types with their config schema (admin add form).

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List Connector Types

List registered connector types with their config schema (admin add form).

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get Connector

Get a connector config by ID (admin only).

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "connector_type": "string",
  • "enabled": true,
  • "scopes": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "redirect_uri": "string",
  • "icon": "string",
  • "status": "unknown",
  • "configured": false
}

Get Connector

Get a connector config by ID (admin only).

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "connector_type": "string",
  • "enabled": true,
  • "scopes": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "redirect_uri": "string",
  • "icon": "string",
  • "status": "unknown",
  • "configured": false
}

Update Connector

Update a connector configuration (admin only).

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Config (object) or Config (null) (Config)
Array of Scopes (strings) or Scopes (null) (Scopes)
Enabled (boolean) or Enabled (null) (Enabled)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "config": { },
  • "scopes": [
    ],
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "connector_type": "string",
  • "enabled": true,
  • "scopes": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "redirect_uri": "string",
  • "icon": "string",
  • "status": "unknown",
  • "configured": false
}

Update Connector

Update a connector configuration (admin only).

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Config (object) or Config (null) (Config)
Array of Scopes (strings) or Scopes (null) (Scopes)
Enabled (boolean) or Enabled (null) (Enabled)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "config": { },
  • "scopes": [
    ],
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "connector_type": "string",
  • "enabled": true,
  • "scopes": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "redirect_uri": "string",
  • "icon": "string",
  • "status": "unknown",
  • "configured": false
}

Delete Connector

Delete a connector (admin only).

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Connector

Delete a connector (admin only).

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Deploy Connector Workload

Run a subscribed connector as a type:connector extension (admin only).

Provisions the connector's workload identity, applies its CR (no public ingress, no external egress), and binds the workload principal so the mint/proxy authorization recognizes the running pod. 202: the workload is scheduled; the extension-operator reconciles it to running asynchronously.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "deployment_id": "6ef0ac85-9892-4664-a2a5-58bf2af5a8a6",
  • "workload_principal_id": "string"
}

Deploy Connector Workload

Run a subscribed connector as a type:connector extension (admin only).

Provisions the connector's workload identity, applies its CR (no public ingress, no external egress), and binds the workload principal so the mint/proxy authorization recognizes the running pod. 202: the workload is scheduled; the extension-operator reconciles it to running asynchronously.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "deployment_id": "6ef0ac85-9892-4664-a2a5-58bf2af5a8a6",
  • "workload_principal_id": "string"
}

Sync Declared Connectors

Subscribe every catalog connector so admins can deploy them (admin only).

Subscribes every connector published to the catalog, making it available to admins. Mirrors apps/tool /remote/sync; the chart's post-install/post-upgrade templates-sync Job calls this on every deploy so a greenfield or updated cluster discovers its connectors with no manual step. Safe to re-run -- already-subscribed connectors are no-ops. Sync never deploys a workload; standing one up is an explicit operator action.

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{ }

Sync Declared Connectors

Subscribe every catalog connector so admins can deploy them (admin only).

Subscribes every connector published to the catalog, making it available to admins. Mirrors apps/tool /remote/sync; the chart's post-install/post-upgrade templates-sync Job calls this on every deploy so a greenfield or updated cluster discovers its connectors with no manual step. Safe to re-run -- already-subscribed connectors are no-ops. Sync never deploys a workload; standing one up is an explicit operator action.

Authorizations:
OAuth2LoginBearerAuth
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{ }

Connect Account

Begin connecting the caller's account, per the connector's manifest flow.

Returns {"auth_url": ...} for redirect (authorization-code) connectors, or {"device_code": {...}} for device-code connectors; the client branches.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{ }

Connect Account

Begin connecting the caller's account, per the connector's manifest flow.

Returns {"auth_url": ...} for redirect (authorization-code) connectors, or {"device_code": {...}} for device-code connectors; the client branches.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{ }

Poll Device Connection

Poll a device-code connect (returns status: pending | connected | expired).

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Poll Device Connection

Poll a device-code connect (returns status: pending | connected | expired).

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Get User Connection

The caller's connection status for a connector.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{ }

Get User Connection

The caller's connection status for a connector.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{ }

Disconnect Account

Disconnect the caller's account from a connector.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Disconnect Account

Disconnect the caller's account from a connector.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Verify Connection

Verify the caller's connection by probing through the deployed connector.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{ }

Verify Connection

Verify the caller's connection by probing through the deployed connector.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
connector_id
required
string <uuid> (Connector Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{ }

List Connector Surface Catalog

Return generic connector surfaces available to the current user/workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List Connector Surface Catalog

Return generic connector surfaces available to the current user/workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Browse Connector Surface

Browse a generic connector surface.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
connector_id
required
string <uuid> (Connector Id)
query Parameters
surface
required
string (Surface) [ 1 .. 64 ] characters
Container Id (string) or Container Id (null) (Container Id)
page_size
integer (Page Size) [ 1 .. 200 ]
Default: 50
Page Token (string) or Page Token (null) (Page Token)
View (string) or View (null) (View)
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "surface": "string",
  • "items": [
    ],
  • "next_page_token": "string",
  • "constraints": [
    ]
}

Browse Connector Surface

Browse a generic connector surface.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
connector_id
required
string <uuid> (Connector Id)
query Parameters
surface
required
string (Surface) [ 1 .. 64 ] characters
Container Id (string) or Container Id (null) (Container Id)
page_size
integer (Page Size) [ 1 .. 200 ]
Default: 50
Page Token (string) or Page Token (null) (Page Token)
View (string) or View (null) (View)
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "surface": "string",
  • "items": [
    ],
  • "next_page_token": "string",
  • "constraints": [
    ]
}

Search Connector Surface

Search a generic connector surface.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
connector_id
required
string <uuid> (Connector Id)
query Parameters
surface
required
string (Surface) [ 1 .. 64 ] characters
q
required
string (Q) [ 1 .. 200 ] characters
Container Id (string) or Container Id (null) (Container Id)
page_size
integer (Page Size) [ 1 .. 200 ]
Default: 50
Page Token (string) or Page Token (null) (Page Token)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "surface": "string",
  • "items": [
    ],
  • "next_page_token": "string",
  • "constraints": [
    ]
}

Search Connector Surface

Search a generic connector surface.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
connector_id
required
string <uuid> (Connector Id)
query Parameters
surface
required
string (Surface) [ 1 .. 64 ] characters
q
required
string (Q) [ 1 .. 200 ] characters
Container Id (string) or Container Id (null) (Container Id)
page_size
integer (Page Size) [ 1 .. 200 ]
Default: 50
Page Token (string) or Page Token (null) (Page Token)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "surface": "string",
  • "items": [
    ],
  • "next_page_token": "string",
  • "constraints": [
    ]
}

Download Connector Surface Content

Download content for a generic connector file node.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
connector_id
required
string <uuid> (Connector Id)
node_id
required
string (Node Id)
query Parameters
surface
required
string (Surface) [ 1 .. 64 ] characters
Drive Id (string) or Drive Id (null) (Drive Id)
Mime Type (string) or Mime Type (null) (Mime Type)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
null

Download Connector Surface Content

Download content for a generic connector file node.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
connector_id
required
string <uuid> (Connector Id)
node_id
required
string (Node Id)
query Parameters
surface
required
string (Surface) [ 1 .. 64 ] characters
Drive Id (string) or Drive Id (null) (Drive Id)
Mime Type (string) or Mime Type (null) (Mime Type)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
null

connectors-public

Connector Oauth Callback

Public OAuth callback: exchange the code, store the user's tokens, notify the opener.

No auth — the request is the provider's redirect. The single-use state identifies connector + user; provider is cosmetic (lets the redirect URI read /google/callback etc.). Routing is entirely state-driven.

path Parameters
provider
required
string (Provider)
query Parameters
code
string (Code)
Default: ""
state
string (State)
Default: ""
error
string (Error)
Default: ""

Responses

Response samples

Content type
application/json
null

Connector Oauth Callback

Public OAuth callback: exchange the code, store the user's tokens, notify the opener.

No auth — the request is the provider's redirect. The single-use state identifies connector + user; provider is cosmetic (lets the redirect URI read /google/callback etc.). Routing is entirely state-driven.

path Parameters
provider
required
string (Provider)
query Parameters
code
string (Code)
Default: ""
state
string (State)
Default: ""
error
string (Error)
Default: ""

Responses

Response samples

Content type
application/json
null

oauth-broker

Create App Installation

Create a new app installation.

The authenticated user becomes the owner of the app.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters

App name

Description (string) or Description (null) (Description)

App description

allowed_tools
Array of strings (Allowed Tools)

List of tool IDs allowed to use this app's connections

App Metadata (object) or App Metadata (null) (App Metadata)

Optional app metadata

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "allowed_tools": [
    ],
  • "app_metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d",
  • "lifecycle_status": "string",
  • "allowed_tools": [
    ],
  • "app_metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z"
}

List App Installations

List app installations.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Owner User Id (string) or Owner User Id (null) (Owner User Id)

Filter by owner

Lifecycle Status (string) or Lifecycle Status (null) (Lifecycle Status)

Filter by status

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0
}

Get App Installation

Get app installation by ID.

Authorizations:
BearerAuthOAuth2Login
path Parameters
app_id
required
string <uuid> (App Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d",
  • "lifecycle_status": "string",
  • "allowed_tools": [
    ],
  • "app_metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z"
}

Update App Installation

Update app installation.

Authorizations:
BearerAuthOAuth2Login
path Parameters
app_id
required
string <uuid> (App Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Array of Allowed Tools (strings) or Allowed Tools (null) (Allowed Tools)
Lifecycle Status (string) or Lifecycle Status (null) (Lifecycle Status)

active or disabled

App Metadata (object) or App Metadata (null) (App Metadata)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "allowed_tools": [
    ],
  • "lifecycle_status": "active",
  • "app_metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d",
  • "lifecycle_status": "string",
  • "allowed_tools": [
    ],
  • "app_metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z"
}

Delete App Installation

Delete app installation.

This cascades to delete all connections and secrets associated with the app.

Authorizations:
BearerAuthOAuth2Login
path Parameters
app_id
required
string <uuid> (App Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Start Google Auth

Start Google OAuth authorization code flow.

Returns an authorization URL to redirect the user to.

Example scopes: "https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/gmail.compose"

Authorizations:
BearerAuthOAuth2Login
query Parameters
app_id
required
string <uuid> (App Id)

App installation ID

scopes
required
string (Scopes)

Comma-separated Google OAuth scopes

Responses

Response samples

Content type
application/json
null

Handle Google Callback

Handle Google OAuth callback.

This endpoint is called by Google after user authorizes the app. Exchanges the authorization code for tokens and creates a connection.

Authorizations:
BearerAuthOAuth2Login
query Parameters
code
required
string (Code)

Authorization code from Google

state
required
string (State)

State parameter for CSRF validation

Scope (string) or Scope (null) (Scope)

Granted scopes

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "app_installation_id": "2287bd4e-dc28-4ba7-a7e1-1d6c0aca1d2a",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "provider": "string",
  • "external_user_id": "string",
  • "external_email": "string",
  • "granted_scopes": [
    ],
  • "expires_at": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "last_refreshed_at": "2019-08-24T14:15:22Z"
}

Get Connection Status

Get connection status for user.

Returns:

  • status: connected, needs_reauth, or disconnected
  • Connection metadata if connected
Authorizations:
BearerAuthOAuth2Login
query Parameters
app_id
required
string <uuid> (App Id)

App installation ID

provider
required
string (Provider)
Enum: "google" "microsoft"

OAuth provider

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "provider": "string",
  • "external_email": "string",
  • "granted_scopes": [
    ],
  • "expires_at": "2019-08-24T14:15:22Z",
  • "connected_at": "2019-08-24T14:15:22Z",
  • "message": "string"
}

Disconnect

Disconnect user from provider.

This will:

  1. Revoke tokens with the provider (best effort)
  2. Delete tokens from Catalog Secret Store
  3. Delete the connection record
Authorizations:
BearerAuthOAuth2Login
query Parameters
app_id
required
string <uuid> (App Id)

App installation ID

provider
required
string (Provider)
Enum: "google" "microsoft"

OAuth provider

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Create Tool Policy

Create a new tool policy.

Tool policies define what operations a tool can perform with a connection.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
app_installation_id
required
string <uuid> (App Installation Id)

App installation ID

tool_id
required
string (Tool Id) [ 1 .. 255 ] characters

Tool identifier (e.g., gmail-read-tool)

provider
required
string (Provider)

Provider (google, microsoft, etc.)

allowed_operations
Array of strings (Allowed Operations)

Allowed operations (e.g., ['gmail.search', 'gmail.getMessage'])

allowed_scope_subset
Array of strings (Allowed Scope Subset)

Allowed OAuth scopes (must be subset of connection scopes)

Policy Metadata (object) or Policy Metadata (null) (Policy Metadata)

Optional policy metadata

Responses

Request samples

Content type
application/json
{
  • "app_installation_id": "2287bd4e-dc28-4ba7-a7e1-1d6c0aca1d2a",
  • "tool_id": "string",
  • "provider": "string",
  • "allowed_operations": [
    ],
  • "allowed_scope_subset": [
    ],
  • "policy_metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "app_installation_id": "2287bd4e-dc28-4ba7-a7e1-1d6c0aca1d2a",
  • "tool_id": "string",
  • "provider": "string",
  • "allowed_operations": [
    ],
  • "allowed_scope_subset": [
    ],
  • "policy_metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List Tool Policies

List tool policies with optional filters.

Authorizations:
BearerAuthOAuth2Login
query Parameters
App Id (string) or App Id (null) (App Id)

Filter by app ID

Tool Id (string) or Tool Id (null) (Tool Id)

Filter by tool ID

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0
}

Get Tool Policy

Get tool policy by policy ID.

Authorizations:
BearerAuthOAuth2Login
path Parameters
policy_id
required
string <uuid> (Policy Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "app_installation_id": "2287bd4e-dc28-4ba7-a7e1-1d6c0aca1d2a",
  • "tool_id": "string",
  • "provider": "string",
  • "allowed_operations": [
    ],
  • "allowed_scope_subset": [
    ],
  • "policy_metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Tool Policy

Update tool policy.

Authorizations:
BearerAuthOAuth2Login
path Parameters
policy_id
required
string <uuid> (Policy Id)
Request Body schema: application/json
required
Array of Allowed Operations (strings) or Allowed Operations (null) (Allowed Operations)
Array of Allowed Scope Subset (strings) or Allowed Scope Subset (null) (Allowed Scope Subset)
Policy Metadata (object) or Policy Metadata (null) (Policy Metadata)

Responses

Request samples

Content type
application/json
{
  • "allowed_operations": [
    ],
  • "allowed_scope_subset": [
    ],
  • "policy_metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "app_installation_id": "2287bd4e-dc28-4ba7-a7e1-1d6c0aca1d2a",
  • "tool_id": "string",
  • "provider": "string",
  • "allowed_operations": [
    ],
  • "allowed_scope_subset": [
    ],
  • "policy_metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Tool Policy

Delete tool policy.

Authorizations:
BearerAuthOAuth2Login
path Parameters
policy_id
required
string <uuid> (Policy Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Mint Ephemeral Token

Mint an ephemeral access token (Mode 2 - Advanced).

WARNING: This endpoint should only be used in high-security environments where:

  • Tools run in controlled compute (same cluster as broker)
  • Network egress is restricted to provider domains only (*.googleapis.com)
  • Tool requires direct SDK access (rare edge cases)

For most use cases, use Proxy Mode (Mode 1) instead, which never exposes tokens.

The minted token is a real provider access token with a broker-tracked lease. Leases automatically expire after the specified duration (1-15 minutes), but provider token lifetime is controlled by the provider and may outlive the broker lease if provider-side revocation fails.

Args: request: Token mint request with app_id, tool_id, provider, scope_subset, lease_duration user: Authenticated user (from JWT)

Returns: Ephemeral access token with lease tracking

Raises: 400: Invalid request (missing connection, policy violation) 403: Tool not authorized to mint tokens 404: Connection not found 500: Provider error

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
app_installation_id
required
string <uuid> (App Installation Id)

App installation ID

tool_id
required
string (Tool Id)

Tool identifier requesting token

provider
required
string (Provider)

Provider (google, microsoft)

Array of Scope Subset (strings) or Scope Subset (null) (Scope Subset)

Optional scope subset (must be subset of connection's granted_scopes)

lease_duration
integer (Lease Duration) [ 60 .. 900 ]
Default: 300

Lease duration in seconds (1-15 minutes, default 5 minutes)

Responses

Request samples

Content type
application/json
{
  • "app_installation_id": "2287bd4e-dc28-4ba7-a7e1-1d6c0aca1d2a",
  • "tool_id": "string",
  • "provider": "string",
  • "scope_subset": [
    ],
  • "lease_duration": 300
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "lease_id": "string",
  • "expires_in": 0,
  • "broker_lease_expires_in": 0,
  • "token_type": "Bearer",
  • "granted_scopes": [
    ]
}

Get Lease Status

Get status of a token lease.

Args: lease_id: Lease identifier from mint response user: Authenticated user (from JWT)

Returns: Lease status including expiry and validity

Raises: 404: Lease not found or user not authorized

Authorizations:
BearerAuthOAuth2Login
path Parameters
lease_id
required
string (Lease Id)

Responses

Response samples

Content type
application/json
{
  • "lease_id": "string",
  • "app_installation_id": "2287bd4e-dc28-4ba7-a7e1-1d6c0aca1d2a",
  • "tool_id": "string",
  • "provider": "string",
  • "granted_scopes": [
    ],
  • "issued_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "revoked_at": "2019-08-24T14:15:22Z",
  • "is_valid": true
}

Revoke Lease

Revoke a token lease early.

This invalidates lease tracking and attempts provider-side token revocation for the underlying OAuth connection. If provider revocation fails, already issued provider tokens may remain valid until the provider's own expiry.

Args: lease_id: Lease identifier user: Authenticated user (from JWT)

Raises: 404: Lease not found or user not authorized

Authorizations:
BearerAuthOAuth2Login
path Parameters
lease_id
required
string (Lease Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Mint Connector Token

Mint a scope-restricted provider token for a connector.

The caller authenticates as the connector's workload (service-account) identity; only the principal bound to the subscription (workload_principal_id) may mint. The credential source follows the connector's declared auth model: per_user_oauth brokers a verified subject's per-user token (refreshed in core), only for a subject whose presented acting-user token verifies (its sub) and that holds a connected connection; service_token returns the connector's admin-configured shared credential, role-entitlement gated, for a verified subject -- or, when the connector opts in via allow_subjectless, with no triggering subject (an autonomous machine identity accountable via its workload binding). The minted token is the provider access token -- the refresh token and client secret never leave core; the mint is lease-tracked for revoke-on-disconnect. Data-plane half of the contract.

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)
Request Body schema: application/json
required
Subject Token (string) or Subject Token (null) (Subject Token)

Acting user's bearer token; its verified sub is authoritative

Subject Id (string) or Subject Id (null) (Subject Id)

Self-asserted subject; honored only under the env-gated PoC fallback

Subject Type (string) or Subject Type (null) (Subject Type)

Audit hint only (e.g. user / group / npe); NOT a trust input

Array of Scope Subset (strings) or Scope Subset (null) (Scope Subset)

Optional subset of the subject's granted scopes (defaults to all)

lease_duration
integer (Lease Duration) [ 60 .. 900 ]
Default: 300

Broker lease TTL in seconds (1-15 min, default 5 min)

Responses

Request samples

Content type
application/json
{
  • "subject_token": "string",
  • "subject_id": "string",
  • "subject_type": "string",
  • "scope_subset": [
    ],
  • "lease_duration": 300
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "lease_id": "string",
  • "granted_scopes": [
    ],
  • "expires_in": 0,
  • "broker_lease_expires_in": 0,
  • "token_type": "Bearer"
}

Proxy With Resource

Proxy request with a resource identifier (e.g., message_id, file_id).

Authorizations:
OAuth2LoginBearerAuth
path Parameters
provider
required
string (Provider)
service
required
string (Service)
operation
required
string (Operation)
resource_id
required
string (Resource Id)
query Parameters
app_id
required
string <uuid> (App Id)

App installation ID

tool_id
required
string (Tool Id)

Tool identifier

Responses

Response samples

Content type
application/json
{ }

Proxy With Resource

Proxy request with a resource identifier (e.g., message_id, file_id).

Authorizations:
OAuth2LoginBearerAuth
path Parameters
provider
required
string (Provider)
service
required
string (Service)
operation
required
string (Operation)
resource_id
required
string (Resource Id)
query Parameters
app_id
required
string <uuid> (App Id)

App installation ID

tool_id
required
string (Tool Id)

Tool identifier

Responses

Response samples

Content type
application/json
{ }

Proxy Request

Proxy request to an external API operation.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
provider
required
string (Provider)
service
required
string (Service)
operation
required
string (Operation)
query Parameters
app_id
required
string <uuid> (App Id)

App installation ID

tool_id
required
string (Tool Id)

Tool identifier

Responses

Response samples

Content type
application/json
{ }

Proxy Request

Proxy request to an external API operation.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
provider
required
string (Provider)
service
required
string (Service)
operation
required
string (Operation)
query Parameters
app_id
required
string <uuid> (App Id)

App installation ID

tool_id
required
string (Tool Id)

Tool identifier

Responses

Response samples

Content type
application/json
{ }

Proxy Connector Request

Execute a subscribed connector's request through core (P1, core-proxied).

The caller authenticates as the connector's workload identity; only the bound workload_principal_id may proxy. Core authorizes the call as the mint does (verified acting subject, connection ownership, scope least-privilege), enforces the connector's egress allowlist, attaches the provider access token, executes the upstream call, and returns the response. The provider token never leaves core; the connector never egresses to the SaaS directly. See contracts/proxy-execute.md.

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)
Request Body schema: application/json
required
Subject Token (string) or Subject Token (null) (Subject Token)

Acting user's bearer token; its verified sub is authoritative

Subject Id (string) or Subject Id (null) (Subject Id)

Self-asserted subject; honored only under the env-gated PoC fallback

Subject Type (string) or Subject Type (null) (Subject Type)

Audit hint only (e.g. user / group / npe); NOT a trust input

Array of Scope Subset (strings) or Scope Subset (null) (Scope Subset)

Optional subset of the subject's granted scopes (defaults to all)

lease_duration
integer (Lease Duration) [ 60 .. 900 ]
Default: 300

Broker lease TTL in seconds (1-15 min, default 5 min)

method
string (Method)
Default: "GET"
Enum: "GET" "POST"

HTTP method (v1: GET or POST)

url
required
string (Url)

Absolute URL; its host must be in the connector's egress allowlist

Params (object) or Params (null) (Params)

Query parameters

Body (object) or Body (null) (Body)

JSON body (POST)

response_format
string (Response Format)
Default: "json"
Enum: "json" "binary"

How core returns the upstream body: parsed JSON (default), or base64-wrapped bytes for binary content such as file downloads

Responses

Request samples

Content type
application/json
{
  • "subject_token": "string",
  • "subject_id": "string",
  • "subject_type": "string",
  • "scope_subset": [
    ],
  • "lease_duration": 300,
  • "method": "GET",
  • "url": "string",
  • "params": { },
  • "body": { },
  • "response_format": "json"
}

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "body": null
}

Proxy Connector Identity

Fetch a connector's account identity through core (the OAuth-callback whoami).

The connector pod has no external egress, so at the OAuth callback it asks core to call the provider's identity endpoint with the freshly-minted access token. Core authorizes the bound workload and enforces the egress allowlist -- the same trust boundary as the execute proxy, minus the connection/subject that don't exist yet.

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)
Request Body schema: application/json
required
method
string (Method)
Default: "GET"
Enum: "GET" "POST"

HTTP method

url
required
string (Url)

Absolute URL; its host must be in the connector's egress allowlist

Params (object) or Params (null) (Params)

Query parameters

Body (object) or Body (null) (Body)

JSON body (POST)

response_format
string (Response Format)
Default: "json"

JSON-only

Value: "json"
access_token
required
string (Access Token)

Freshly-minted provider token; core attaches it as the bearer

Responses

Request samples

Content type
application/json
{
  • "method": "GET",
  • "url": "string",
  • "params": { },
  • "body": { },
  • "response_format": "json",
  • "access_token": "string"
}

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "body": null
}

app-installations

Create App Installation

Create a new app installation.

The authenticated user becomes the owner of the app.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters

App name

Description (string) or Description (null) (Description)

App description

allowed_tools
Array of strings (Allowed Tools)

List of tool IDs allowed to use this app's connections

App Metadata (object) or App Metadata (null) (App Metadata)

Optional app metadata

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "allowed_tools": [
    ],
  • "app_metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d",
  • "lifecycle_status": "string",
  • "allowed_tools": [
    ],
  • "app_metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z"
}

List App Installations

List app installations.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Owner User Id (string) or Owner User Id (null) (Owner User Id)

Filter by owner

Lifecycle Status (string) or Lifecycle Status (null) (Lifecycle Status)

Filter by status

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0
}

Get App Installation

Get app installation by ID.

Authorizations:
BearerAuthOAuth2Login
path Parameters
app_id
required
string <uuid> (App Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d",
  • "lifecycle_status": "string",
  • "allowed_tools": [
    ],
  • "app_metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z"
}

Update App Installation

Update app installation.

Authorizations:
BearerAuthOAuth2Login
path Parameters
app_id
required
string <uuid> (App Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Array of Allowed Tools (strings) or Allowed Tools (null) (Allowed Tools)
Lifecycle Status (string) or Lifecycle Status (null) (Lifecycle Status)

active or disabled

App Metadata (object) or App Metadata (null) (App Metadata)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "allowed_tools": [
    ],
  • "lifecycle_status": "active",
  • "app_metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d",
  • "lifecycle_status": "string",
  • "allowed_tools": [
    ],
  • "app_metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z"
}

Delete App Installation

Delete app installation.

This cascades to delete all connections and secrets associated with the app.

Authorizations:
BearerAuthOAuth2Login
path Parameters
app_id
required
string <uuid> (App Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

oauth-auth

Start Google Auth

Start Google OAuth authorization code flow.

Returns an authorization URL to redirect the user to.

Example scopes: "https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/gmail.compose"

Authorizations:
BearerAuthOAuth2Login
query Parameters
app_id
required
string <uuid> (App Id)

App installation ID

scopes
required
string (Scopes)

Comma-separated Google OAuth scopes

Responses

Response samples

Content type
application/json
null

Handle Google Callback

Handle Google OAuth callback.

This endpoint is called by Google after user authorizes the app. Exchanges the authorization code for tokens and creates a connection.

Authorizations:
BearerAuthOAuth2Login
query Parameters
code
required
string (Code)

Authorization code from Google

state
required
string (State)

State parameter for CSRF validation

Scope (string) or Scope (null) (Scope)

Granted scopes

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "app_installation_id": "2287bd4e-dc28-4ba7-a7e1-1d6c0aca1d2a",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "provider": "string",
  • "external_user_id": "string",
  • "external_email": "string",
  • "granted_scopes": [
    ],
  • "expires_at": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "last_refreshed_at": "2019-08-24T14:15:22Z"
}

connections

Get Connection Status

Get connection status for user.

Returns:

  • status: connected, needs_reauth, or disconnected
  • Connection metadata if connected
Authorizations:
BearerAuthOAuth2Login
query Parameters
app_id
required
string <uuid> (App Id)

App installation ID

provider
required
string (Provider)
Enum: "google" "microsoft"

OAuth provider

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "provider": "string",
  • "external_email": "string",
  • "granted_scopes": [
    ],
  • "expires_at": "2019-08-24T14:15:22Z",
  • "connected_at": "2019-08-24T14:15:22Z",
  • "message": "string"
}

Disconnect

Disconnect user from provider.

This will:

  1. Revoke tokens with the provider (best effort)
  2. Delete tokens from Catalog Secret Store
  3. Delete the connection record
Authorizations:
BearerAuthOAuth2Login
query Parameters
app_id
required
string <uuid> (App Id)

App installation ID

provider
required
string (Provider)
Enum: "google" "microsoft"

OAuth provider

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

tool-policies

Create Tool Policy

Create a new tool policy.

Tool policies define what operations a tool can perform with a connection.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
app_installation_id
required
string <uuid> (App Installation Id)

App installation ID

tool_id
required
string (Tool Id) [ 1 .. 255 ] characters

Tool identifier (e.g., gmail-read-tool)

provider
required
string (Provider)

Provider (google, microsoft, etc.)

allowed_operations
Array of strings (Allowed Operations)

Allowed operations (e.g., ['gmail.search', 'gmail.getMessage'])

allowed_scope_subset
Array of strings (Allowed Scope Subset)

Allowed OAuth scopes (must be subset of connection scopes)

Policy Metadata (object) or Policy Metadata (null) (Policy Metadata)

Optional policy metadata

Responses

Request samples

Content type
application/json
{
  • "app_installation_id": "2287bd4e-dc28-4ba7-a7e1-1d6c0aca1d2a",
  • "tool_id": "string",
  • "provider": "string",
  • "allowed_operations": [
    ],
  • "allowed_scope_subset": [
    ],
  • "policy_metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "app_installation_id": "2287bd4e-dc28-4ba7-a7e1-1d6c0aca1d2a",
  • "tool_id": "string",
  • "provider": "string",
  • "allowed_operations": [
    ],
  • "allowed_scope_subset": [
    ],
  • "policy_metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List Tool Policies

List tool policies with optional filters.

Authorizations:
BearerAuthOAuth2Login
query Parameters
App Id (string) or App Id (null) (App Id)

Filter by app ID

Tool Id (string) or Tool Id (null) (Tool Id)

Filter by tool ID

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0
}

Get Tool Policy

Get tool policy by policy ID.

Authorizations:
BearerAuthOAuth2Login
path Parameters
policy_id
required
string <uuid> (Policy Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "app_installation_id": "2287bd4e-dc28-4ba7-a7e1-1d6c0aca1d2a",
  • "tool_id": "string",
  • "provider": "string",
  • "allowed_operations": [
    ],
  • "allowed_scope_subset": [
    ],
  • "policy_metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Tool Policy

Update tool policy.

Authorizations:
BearerAuthOAuth2Login
path Parameters
policy_id
required
string <uuid> (Policy Id)
Request Body schema: application/json
required
Array of Allowed Operations (strings) or Allowed Operations (null) (Allowed Operations)
Array of Allowed Scope Subset (strings) or Allowed Scope Subset (null) (Allowed Scope Subset)
Policy Metadata (object) or Policy Metadata (null) (Policy Metadata)

Responses

Request samples

Content type
application/json
{
  • "allowed_operations": [
    ],
  • "allowed_scope_subset": [
    ],
  • "policy_metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "app_installation_id": "2287bd4e-dc28-4ba7-a7e1-1d6c0aca1d2a",
  • "tool_id": "string",
  • "provider": "string",
  • "allowed_operations": [
    ],
  • "allowed_scope_subset": [
    ],
  • "policy_metadata": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Tool Policy

Delete tool policy.

Authorizations:
BearerAuthOAuth2Login
path Parameters
policy_id
required
string <uuid> (Policy Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

ephemeral-tokens

Mint Ephemeral Token

Mint an ephemeral access token (Mode 2 - Advanced).

WARNING: This endpoint should only be used in high-security environments where:

  • Tools run in controlled compute (same cluster as broker)
  • Network egress is restricted to provider domains only (*.googleapis.com)
  • Tool requires direct SDK access (rare edge cases)

For most use cases, use Proxy Mode (Mode 1) instead, which never exposes tokens.

The minted token is a real provider access token with a broker-tracked lease. Leases automatically expire after the specified duration (1-15 minutes), but provider token lifetime is controlled by the provider and may outlive the broker lease if provider-side revocation fails.

Args: request: Token mint request with app_id, tool_id, provider, scope_subset, lease_duration user: Authenticated user (from JWT)

Returns: Ephemeral access token with lease tracking

Raises: 400: Invalid request (missing connection, policy violation) 403: Tool not authorized to mint tokens 404: Connection not found 500: Provider error

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
app_installation_id
required
string <uuid> (App Installation Id)

App installation ID

tool_id
required
string (Tool Id)

Tool identifier requesting token

provider
required
string (Provider)

Provider (google, microsoft)

Array of Scope Subset (strings) or Scope Subset (null) (Scope Subset)

Optional scope subset (must be subset of connection's granted_scopes)

lease_duration
integer (Lease Duration) [ 60 .. 900 ]
Default: 300

Lease duration in seconds (1-15 minutes, default 5 minutes)

Responses

Request samples

Content type
application/json
{
  • "app_installation_id": "2287bd4e-dc28-4ba7-a7e1-1d6c0aca1d2a",
  • "tool_id": "string",
  • "provider": "string",
  • "scope_subset": [
    ],
  • "lease_duration": 300
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "lease_id": "string",
  • "expires_in": 0,
  • "broker_lease_expires_in": 0,
  • "token_type": "Bearer",
  • "granted_scopes": [
    ]
}

Get Lease Status

Get status of a token lease.

Args: lease_id: Lease identifier from mint response user: Authenticated user (from JWT)

Returns: Lease status including expiry and validity

Raises: 404: Lease not found or user not authorized

Authorizations:
BearerAuthOAuth2Login
path Parameters
lease_id
required
string (Lease Id)

Responses

Response samples

Content type
application/json
{
  • "lease_id": "string",
  • "app_installation_id": "2287bd4e-dc28-4ba7-a7e1-1d6c0aca1d2a",
  • "tool_id": "string",
  • "provider": "string",
  • "granted_scopes": [
    ],
  • "issued_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "revoked_at": "2019-08-24T14:15:22Z",
  • "is_valid": true
}

Revoke Lease

Revoke a token lease early.

This invalidates lease tracking and attempts provider-side token revocation for the underlying OAuth connection. If provider revocation fails, already issued provider tokens may remain valid until the provider's own expiry.

Args: lease_id: Lease identifier user: Authenticated user (from JWT)

Raises: 404: Lease not found or user not authorized

Authorizations:
BearerAuthOAuth2Login
path Parameters
lease_id
required
string (Lease Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Mint Connector Token

Mint a scope-restricted provider token for a connector.

The caller authenticates as the connector's workload (service-account) identity; only the principal bound to the subscription (workload_principal_id) may mint. The credential source follows the connector's declared auth model: per_user_oauth brokers a verified subject's per-user token (refreshed in core), only for a subject whose presented acting-user token verifies (its sub) and that holds a connected connection; service_token returns the connector's admin-configured shared credential, role-entitlement gated, for a verified subject -- or, when the connector opts in via allow_subjectless, with no triggering subject (an autonomous machine identity accountable via its workload binding). The minted token is the provider access token -- the refresh token and client secret never leave core; the mint is lease-tracked for revoke-on-disconnect. Data-plane half of the contract.

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)
Request Body schema: application/json
required
Subject Token (string) or Subject Token (null) (Subject Token)

Acting user's bearer token; its verified sub is authoritative

Subject Id (string) or Subject Id (null) (Subject Id)

Self-asserted subject; honored only under the env-gated PoC fallback

Subject Type (string) or Subject Type (null) (Subject Type)

Audit hint only (e.g. user / group / npe); NOT a trust input

Array of Scope Subset (strings) or Scope Subset (null) (Scope Subset)

Optional subset of the subject's granted scopes (defaults to all)

lease_duration
integer (Lease Duration) [ 60 .. 900 ]
Default: 300

Broker lease TTL in seconds (1-15 min, default 5 min)

Responses

Request samples

Content type
application/json
{
  • "subject_token": "string",
  • "subject_id": "string",
  • "subject_type": "string",
  • "scope_subset": [
    ],
  • "lease_duration": 300
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "lease_id": "string",
  • "granted_scopes": [
    ],
  • "expires_in": 0,
  • "broker_lease_expires_in": 0,
  • "token_type": "Bearer"
}

oauth-broker-tokens

Mint Ephemeral Token

Mint an ephemeral access token (Mode 2 - Advanced).

WARNING: This endpoint should only be used in high-security environments where:

  • Tools run in controlled compute (same cluster as broker)
  • Network egress is restricted to provider domains only (*.googleapis.com)
  • Tool requires direct SDK access (rare edge cases)

For most use cases, use Proxy Mode (Mode 1) instead, which never exposes tokens.

The minted token is a real provider access token with a broker-tracked lease. Leases automatically expire after the specified duration (1-15 minutes), but provider token lifetime is controlled by the provider and may outlive the broker lease if provider-side revocation fails.

Args: request: Token mint request with app_id, tool_id, provider, scope_subset, lease_duration user: Authenticated user (from JWT)

Returns: Ephemeral access token with lease tracking

Raises: 400: Invalid request (missing connection, policy violation) 403: Tool not authorized to mint tokens 404: Connection not found 500: Provider error

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
app_installation_id
required
string <uuid> (App Installation Id)

App installation ID

tool_id
required
string (Tool Id)

Tool identifier requesting token

provider
required
string (Provider)

Provider (google, microsoft)

Array of Scope Subset (strings) or Scope Subset (null) (Scope Subset)

Optional scope subset (must be subset of connection's granted_scopes)

lease_duration
integer (Lease Duration) [ 60 .. 900 ]
Default: 300

Lease duration in seconds (1-15 minutes, default 5 minutes)

Responses

Request samples

Content type
application/json
{
  • "app_installation_id": "2287bd4e-dc28-4ba7-a7e1-1d6c0aca1d2a",
  • "tool_id": "string",
  • "provider": "string",
  • "scope_subset": [
    ],
  • "lease_duration": 300
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "lease_id": "string",
  • "expires_in": 0,
  • "broker_lease_expires_in": 0,
  • "token_type": "Bearer",
  • "granted_scopes": [
    ]
}

Get Lease Status

Get status of a token lease.

Args: lease_id: Lease identifier from mint response user: Authenticated user (from JWT)

Returns: Lease status including expiry and validity

Raises: 404: Lease not found or user not authorized

Authorizations:
BearerAuthOAuth2Login
path Parameters
lease_id
required
string (Lease Id)

Responses

Response samples

Content type
application/json
{
  • "lease_id": "string",
  • "app_installation_id": "2287bd4e-dc28-4ba7-a7e1-1d6c0aca1d2a",
  • "tool_id": "string",
  • "provider": "string",
  • "granted_scopes": [
    ],
  • "issued_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "revoked_at": "2019-08-24T14:15:22Z",
  • "is_valid": true
}

Revoke Lease

Revoke a token lease early.

This invalidates lease tracking and attempts provider-side token revocation for the underlying OAuth connection. If provider revocation fails, already issued provider tokens may remain valid until the provider's own expiry.

Args: lease_id: Lease identifier user: Authenticated user (from JWT)

Raises: 404: Lease not found or user not authorized

Authorizations:
BearerAuthOAuth2Login
path Parameters
lease_id
required
string (Lease Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Mint Connector Token

Mint a scope-restricted provider token for a connector.

The caller authenticates as the connector's workload (service-account) identity; only the principal bound to the subscription (workload_principal_id) may mint. The credential source follows the connector's declared auth model: per_user_oauth brokers a verified subject's per-user token (refreshed in core), only for a subject whose presented acting-user token verifies (its sub) and that holds a connected connection; service_token returns the connector's admin-configured shared credential, role-entitlement gated, for a verified subject -- or, when the connector opts in via allow_subjectless, with no triggering subject (an autonomous machine identity accountable via its workload binding). The minted token is the provider access token -- the refresh token and client secret never leave core; the mint is lease-tracked for revoke-on-disconnect. Data-plane half of the contract.

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)
Request Body schema: application/json
required
Subject Token (string) or Subject Token (null) (Subject Token)

Acting user's bearer token; its verified sub is authoritative

Subject Id (string) or Subject Id (null) (Subject Id)

Self-asserted subject; honored only under the env-gated PoC fallback

Subject Type (string) or Subject Type (null) (Subject Type)

Audit hint only (e.g. user / group / npe); NOT a trust input

Array of Scope Subset (strings) or Scope Subset (null) (Scope Subset)

Optional subset of the subject's granted scopes (defaults to all)

lease_duration
integer (Lease Duration) [ 60 .. 900 ]
Default: 300

Broker lease TTL in seconds (1-15 min, default 5 min)

Responses

Request samples

Content type
application/json
{
  • "subject_token": "string",
  • "subject_id": "string",
  • "subject_type": "string",
  • "scope_subset": [
    ],
  • "lease_duration": 300
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "lease_id": "string",
  • "granted_scopes": [
    ],
  • "expires_in": 0,
  • "broker_lease_expires_in": 0,
  • "token_type": "Bearer"
}

proxy-mode

Proxy With Resource

Proxy request with a resource identifier (e.g., message_id, file_id).

Authorizations:
OAuth2LoginBearerAuth
path Parameters
provider
required
string (Provider)
service
required
string (Service)
operation
required
string (Operation)
resource_id
required
string (Resource Id)
query Parameters
app_id
required
string <uuid> (App Id)

App installation ID

tool_id
required
string (Tool Id)

Tool identifier

Responses

Response samples

Content type
application/json
{ }

Proxy With Resource

Proxy request with a resource identifier (e.g., message_id, file_id).

Authorizations:
OAuth2LoginBearerAuth
path Parameters
provider
required
string (Provider)
service
required
string (Service)
operation
required
string (Operation)
resource_id
required
string (Resource Id)
query Parameters
app_id
required
string <uuid> (App Id)

App installation ID

tool_id
required
string (Tool Id)

Tool identifier

Responses

Response samples

Content type
application/json
{ }

Proxy Request

Proxy request to an external API operation.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
provider
required
string (Provider)
service
required
string (Service)
operation
required
string (Operation)
query Parameters
app_id
required
string <uuid> (App Id)

App installation ID

tool_id
required
string (Tool Id)

Tool identifier

Responses

Response samples

Content type
application/json
{ }

Proxy Request

Proxy request to an external API operation.

Authorizations:
OAuth2LoginBearerAuth
path Parameters
provider
required
string (Provider)
service
required
string (Service)
operation
required
string (Operation)
query Parameters
app_id
required
string <uuid> (App Id)

App installation ID

tool_id
required
string (Tool Id)

Tool identifier

Responses

Response samples

Content type
application/json
{ }

connector-proxy

Proxy Connector Request

Execute a subscribed connector's request through core (P1, core-proxied).

The caller authenticates as the connector's workload identity; only the bound workload_principal_id may proxy. Core authorizes the call as the mint does (verified acting subject, connection ownership, scope least-privilege), enforces the connector's egress allowlist, attaches the provider access token, executes the upstream call, and returns the response. The provider token never leaves core; the connector never egresses to the SaaS directly. See contracts/proxy-execute.md.

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)
Request Body schema: application/json
required
Subject Token (string) or Subject Token (null) (Subject Token)

Acting user's bearer token; its verified sub is authoritative

Subject Id (string) or Subject Id (null) (Subject Id)

Self-asserted subject; honored only under the env-gated PoC fallback

Subject Type (string) or Subject Type (null) (Subject Type)

Audit hint only (e.g. user / group / npe); NOT a trust input

Array of Scope Subset (strings) or Scope Subset (null) (Scope Subset)

Optional subset of the subject's granted scopes (defaults to all)

lease_duration
integer (Lease Duration) [ 60 .. 900 ]
Default: 300

Broker lease TTL in seconds (1-15 min, default 5 min)

method
string (Method)
Default: "GET"
Enum: "GET" "POST"

HTTP method (v1: GET or POST)

url
required
string (Url)

Absolute URL; its host must be in the connector's egress allowlist

Params (object) or Params (null) (Params)

Query parameters

Body (object) or Body (null) (Body)

JSON body (POST)

response_format
string (Response Format)
Default: "json"
Enum: "json" "binary"

How core returns the upstream body: parsed JSON (default), or base64-wrapped bytes for binary content such as file downloads

Responses

Request samples

Content type
application/json
{
  • "subject_token": "string",
  • "subject_id": "string",
  • "subject_type": "string",
  • "scope_subset": [
    ],
  • "lease_duration": 300,
  • "method": "GET",
  • "url": "string",
  • "params": { },
  • "body": { },
  • "response_format": "json"
}

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "body": null
}

Proxy Connector Request

Execute a subscribed connector's request through core (P1, core-proxied).

The caller authenticates as the connector's workload identity; only the bound workload_principal_id may proxy. Core authorizes the call as the mint does (verified acting subject, connection ownership, scope least-privilege), enforces the connector's egress allowlist, attaches the provider access token, executes the upstream call, and returns the response. The provider token never leaves core; the connector never egresses to the SaaS directly. See contracts/proxy-execute.md.

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)
Request Body schema: application/json
required
Subject Token (string) or Subject Token (null) (Subject Token)

Acting user's bearer token; its verified sub is authoritative

Subject Id (string) or Subject Id (null) (Subject Id)

Self-asserted subject; honored only under the env-gated PoC fallback

Subject Type (string) or Subject Type (null) (Subject Type)

Audit hint only (e.g. user / group / npe); NOT a trust input

Array of Scope Subset (strings) or Scope Subset (null) (Scope Subset)

Optional subset of the subject's granted scopes (defaults to all)

lease_duration
integer (Lease Duration) [ 60 .. 900 ]
Default: 300

Broker lease TTL in seconds (1-15 min, default 5 min)

method
string (Method)
Default: "GET"
Enum: "GET" "POST"

HTTP method (v1: GET or POST)

url
required
string (Url)

Absolute URL; its host must be in the connector's egress allowlist

Params (object) or Params (null) (Params)

Query parameters

Body (object) or Body (null) (Body)

JSON body (POST)

response_format
string (Response Format)
Default: "json"
Enum: "json" "binary"

How core returns the upstream body: parsed JSON (default), or base64-wrapped bytes for binary content such as file downloads

Responses

Request samples

Content type
application/json
{
  • "subject_token": "string",
  • "subject_id": "string",
  • "subject_type": "string",
  • "scope_subset": [
    ],
  • "lease_duration": 300,
  • "method": "GET",
  • "url": "string",
  • "params": { },
  • "body": { },
  • "response_format": "json"
}

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "body": null
}

Proxy Connector Identity

Fetch a connector's account identity through core (the OAuth-callback whoami).

The connector pod has no external egress, so at the OAuth callback it asks core to call the provider's identity endpoint with the freshly-minted access token. Core authorizes the bound workload and enforces the egress allowlist -- the same trust boundary as the execute proxy, minus the connection/subject that don't exist yet.

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)
Request Body schema: application/json
required
method
string (Method)
Default: "GET"
Enum: "GET" "POST"

HTTP method

url
required
string (Url)

Absolute URL; its host must be in the connector's egress allowlist

Params (object) or Params (null) (Params)

Query parameters

Body (object) or Body (null) (Body)

JSON body (POST)

response_format
string (Response Format)
Default: "json"

JSON-only

Value: "json"
access_token
required
string (Access Token)

Freshly-minted provider token; core attaches it as the bearer

Responses

Request samples

Content type
application/json
{
  • "method": "GET",
  • "url": "string",
  • "params": { },
  • "body": { },
  • "response_format": "json",
  • "access_token": "string"
}

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "body": null
}

Proxy Connector Identity

Fetch a connector's account identity through core (the OAuth-callback whoami).

The connector pod has no external egress, so at the OAuth callback it asks core to call the provider's identity endpoint with the freshly-minted access token. Core authorizes the bound workload and enforces the egress allowlist -- the same trust boundary as the execute proxy, minus the connection/subject that don't exist yet.

Authorizations:
BearerAuthOAuth2Login
path Parameters
connector_id
required
string <uuid> (Connector Id)
Request Body schema: application/json
required
method
string (Method)
Default: "GET"
Enum: "GET" "POST"

HTTP method

url
required
string (Url)

Absolute URL; its host must be in the connector's egress allowlist

Params (object) or Params (null) (Params)

Query parameters

Body (object) or Body (null) (Body)

JSON body (POST)

response_format
string (Response Format)
Default: "json"

JSON-only

Value: "json"
access_token
required
string (Access Token)

Freshly-minted provider token; core attaches it as the bearer

Responses

Request samples

Content type
application/json
{
  • "method": "GET",
  • "url": "string",
  • "params": { },
  • "body": { },
  • "response_format": "json",
  • "access_token": "string"
}

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "body": null
}

skills

Import Skill Package

Import a draft skill package.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: multipart/form-data
required
file
required
string <application/octet-stream> (File)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "display_name": "string",
  • "description": "string",
  • "category": "string",
  • "trigger": { },
  • "inputs": [
    ],
  • "classification": "string",
  • "status": "string",
  • "tags": [
    ],
  • "content_checksum": "string",
  • "metadata": { },
  • "package_summary": {
    },
  • "created_by": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List Skills

List tenant-scoped skills.

Authorizations:
BearerAuthOAuth2Login
query Parameters
Q (string) or Q (null) (Q)

Search query

Category (string) or Category (null) (Category)

Category filter

Tag (string) or Tag (null) (Tag)

Tag filter

Status (string) or Status (null) (Status)

Status filter

page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 0,
  • "page_size": 0
}

Get Skill

Return tenant-scoped skill detail.

Authorizations:
BearerAuthOAuth2Login
path Parameters
skill_id
required
string <uuid> (Skill Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "display_name": "string",
  • "description": "string",
  • "category": "string",
  • "trigger": { },
  • "inputs": [
    ],
  • "classification": "string",
  • "status": "string",
  • "tags": [
    ],
  • "content_checksum": "string",
  • "metadata": { },
  • "package_summary": {
    },
  • "created_by": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Skill Metadata

Update mutable skill metadata.

Authorizations:
BearerAuthOAuth2Login
path Parameters
skill_id
required
string <uuid> (Skill Id)
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "display_name": "string",
  • "description": "string",
  • "category": "string",
  • "trigger": { },
  • "inputs": [
    ],
  • "classification": "string",
  • "status": "string",
  • "tags": [
    ],
  • "content_checksum": "string",
  • "metadata": { },
  • "package_summary": {
    },
  • "created_by": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Skill

Soft-delete a skill library entry.

Authorizations:
BearerAuthOAuth2Login
path Parameters
skill_id
required
string <uuid> (Skill Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Export Skill Package

Export the current skill package for operator workflows.

Authorizations:
BearerAuthOAuth2Login
path Parameters
skill_id
required
string <uuid> (Skill Id)

Responses

Response samples

Content type
application/json
null

Get Skill Package

Return the published skill package bytes.

Authorizations:
BearerAuthOAuth2Login
path Parameters
skill_id
required
string <uuid> (Skill Id)

Responses

Response samples

Content type
application/json
null

Export Skills Bundle

Export one or more current skill packages as a zip bundle.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
skill_ids
required
Array of strings <uuid> (Skill Ids) [ 1 .. 100 ] items [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "skill_ids": [
    ]
}

Response samples

Content type
application/json
null

workrooms

Create Workroom

Create a new workroom associated with the calling user.

This route mints new state unrelated to the currently bound workroom, so it should block non-admin Global writes without requiring write-caliber access to whatever shared workroom the caller happens to be viewing.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters
type
required
string (WorkroomType)
Enum: "ephemeral" "persistent"

ephemeral or persistent

Description (string) or Description (null) (Description)
Array of Labels (strings) or Labels (null) (Labels)
Classification (string) or Classification (null) (Classification)
Attributes (object) or Attributes (null) (Attributes)

Extensible key-value pairs (mission_id, template_id, etc.)

Array of Scg References (strings) or Scg References (null) (Scg References)

Security Classification Guide identifiers (WR-CLF-1)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "ephemeral",
  • "description": "string",
  • "labels": [
    ],
  • "classification": "string",
  • "attributes": { },
  • "scg_references": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "string",
  • "owner_user_id": "string",
  • "name": "string",
  • "type": "string",
  • "description": "string",
  • "labels": [
    ],
  • "classification": "string",
  • "attributes": { },
  • "scg_references": [
    ],
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "member_count": 1,
  • "membership_role": "string",
  • "is_owner": true,
  • "is_shared": false,
  • "owner_username": "string",
  • "owner_email": "string"
}

Create Workroom

Create a new workroom associated with the calling user.

This route mints new state unrelated to the currently bound workroom, so it should block non-admin Global writes without requiring write-caliber access to whatever shared workroom the caller happens to be viewing.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters
type
required
string (WorkroomType)
Enum: "ephemeral" "persistent"

ephemeral or persistent

Description (string) or Description (null) (Description)
Array of Labels (strings) or Labels (null) (Labels)
Classification (string) or Classification (null) (Classification)
Attributes (object) or Attributes (null) (Attributes)

Extensible key-value pairs (mission_id, template_id, etc.)

Array of Scg References (strings) or Scg References (null) (Scg References)

Security Classification Guide identifiers (WR-CLF-1)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "ephemeral",
  • "description": "string",
  • "labels": [
    ],
  • "classification": "string",
  • "attributes": { },
  • "scg_references": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "string",
  • "owner_user_id": "string",
  • "name": "string",
  • "type": "string",
  • "description": "string",
  • "labels": [
    ],
  • "classification": "string",
  • "attributes": { },
  • "scg_references": [
    ],
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "member_count": 1,
  • "membership_role": "string",
  • "is_owner": true,
  • "is_shared": false,
  • "owner_username": "string",
  • "owner_email": "string"
}

List Workrooms

List workrooms owned by the calling user.

Authorizations:
BearerAuthOAuth2Login
query Parameters
include_archived
boolean (Include Archived)
Default: false

Include archived workrooms in response

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List Workrooms

List workrooms owned by the calling user.

Authorizations:
BearerAuthOAuth2Login
query Parameters
include_archived
boolean (Include Archived)
Default: false

Include archived workrooms in response

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get Workroom Manager Path

Return the canonical public path and compatibility aliases for Workroom Manager.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "ui_enabled": true,
  • "extension_enabled": false,
  • "launch_enabled": false,
  • "primary_path": "string",
  • "launch_path": "string",
  • "alias_paths": [
    ]
}

Get Workroom Manager Path

Return the canonical public path and compatibility aliases for Workroom Manager.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "ui_enabled": true,
  • "extension_enabled": false,
  • "launch_enabled": false,
  • "primary_path": "string",
  • "launch_path": "string",
  • "alias_paths": [
    ]
}

Get Workroom

Get workroom metadata by ID.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "string",
  • "owner_user_id": "string",
  • "name": "string",
  • "type": "string",
  • "description": "string",
  • "labels": [
    ],
  • "classification": "string",
  • "attributes": { },
  • "scg_references": [
    ],
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "member_count": 1,
  • "membership_role": "string",
  • "is_owner": true,
  • "is_shared": false,
  • "owner_username": "string",
  • "owner_email": "string"
}

Get Workroom

Get workroom metadata by ID.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "string",
  • "owner_user_id": "string",
  • "name": "string",
  • "type": "string",
  • "description": "string",
  • "labels": [
    ],
  • "classification": "string",
  • "attributes": { },
  • "scg_references": [
    ],
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "member_count": 1,
  • "membership_role": "string",
  • "is_owner": true,
  • "is_shared": false,
  • "owner_username": "string",
  • "owner_email": "string"
}

Update Workroom

Update workroom metadata (partial update).

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Array of Labels (strings) or Labels (null) (Labels)
Classification (string) or Classification (null) (Classification)
Attributes (object) or Attributes (null) (Attributes)
Array of Scg References (strings) or Scg References (null) (Scg References)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "labels": [
    ],
  • "classification": "string",
  • "attributes": { },
  • "scg_references": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "string",
  • "owner_user_id": "string",
  • "name": "string",
  • "type": "string",
  • "description": "string",
  • "labels": [
    ],
  • "classification": "string",
  • "attributes": { },
  • "scg_references": [
    ],
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "member_count": 1,
  • "membership_role": "string",
  • "is_owner": true,
  • "is_shared": false,
  • "owner_username": "string",
  • "owner_email": "string"
}

Update Workroom

Update workroom metadata (partial update).

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Description (string) or Description (null) (Description)
Array of Labels (strings) or Labels (null) (Labels)
Classification (string) or Classification (null) (Classification)
Attributes (object) or Attributes (null) (Attributes)
Array of Scg References (strings) or Scg References (null) (Scg References)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "labels": [
    ],
  • "classification": "string",
  • "attributes": { },
  • "scg_references": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "string",
  • "owner_user_id": "string",
  • "name": "string",
  • "type": "string",
  • "description": "string",
  • "labels": [
    ],
  • "classification": "string",
  • "attributes": { },
  • "scg_references": [
    ],
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "member_count": 1,
  • "membership_role": "string",
  • "is_owner": true,
  • "is_shared": false,
  • "owner_username": "string",
  • "owner_email": "string"
}

Delete Workroom

Delete/purge a workroom and all associated resources.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "status": "string",
  • "message": "string"
}

Delete Workroom

Delete/purge a workroom and all associated resources.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "status": "string",
  • "message": "string"
}

List Workroom Members

List the visible memberships for a workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
query Parameters
include_inactive
boolean (Include Inactive)
Default: false

Include inactive historical memberships in response

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List Workroom Members

List the visible memberships for a workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
query Parameters
include_inactive
boolean (Include Inactive)
Default: false

Include inactive historical memberships in response

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add Workroom Member

Add or re-activate a workroom member.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
Request Body schema: application/json
required
email
required
string <email> (Email) <= 320 characters
role
string (WorkroomRole)
Default: "viewer"
Enum: "owner" "editor" "viewer"

Canonical workroom member roles for D180 sharing.

attested
boolean (Attested)
Default: false

Caller confirmed the share attestation step

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "role": "owner",
  • "attested": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "tenant_id": "string",
  • "user_id": "string",
  • "role": "string",
  • "invited_by_user_id": "string",
  • "active": true,
  • "joined_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "removed_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "email": "string",
  • "active_session_count": 0,
  • "is_primary_owner": false
}

Add Workroom Member

Add or re-activate a workroom member.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
Request Body schema: application/json
required
email
required
string <email> (Email) <= 320 characters
role
string (WorkroomRole)
Default: "viewer"
Enum: "owner" "editor" "viewer"

Canonical workroom member roles for D180 sharing.

attested
boolean (Attested)
Default: false

Caller confirmed the share attestation step

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "role": "owner",
  • "attested": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "tenant_id": "string",
  • "user_id": "string",
  • "role": "string",
  • "invited_by_user_id": "string",
  • "active": true,
  • "joined_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "removed_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "email": "string",
  • "active_session_count": 0,
  • "is_primary_owner": false
}

List Workroom Events

List recent workroom activity for runtime/audit timeline rendering.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
query Parameters
limit
integer (Limit) [ 1 .. 100 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List Workroom Events

List recent workroom activity for runtime/audit timeline rendering.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
query Parameters
limit
integer (Limit) [ 1 .. 100 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Stream Workroom Events

Stream workroom runtime events as server-sent events.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
query Parameters
Since (string) or Since (null) (Since)
header Parameters
Last-Event-Id (string) or Last-Event-Id (null) (Last-Event-Id)

Responses

Response samples

Content type
application/json
null

Stream Workroom Events

Stream workroom runtime events as server-sent events.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
query Parameters
Since (string) or Since (null) (Since)
header Parameters
Last-Event-Id (string) or Last-Event-Id (null) (Last-Event-Id)

Responses

Response samples

Content type
application/json
null

List Workroom Threads

List shared collaboration threads for a workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List Workroom Threads

List shared collaboration threads for a workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create Workroom Thread

Create a shared thread inside a workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
Request Body schema: application/json
required
title
required
string (Title) [ 1 .. 255 ] characters
Thread Key (string) or Thread Key (null) (Thread Key)
Opening Message (string) or Opening Message (null) (Opening Message)

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "thread_key": "string",
  • "opening_message": "string"
}

Response samples

Content type
application/json
{
  • "thread_key": "string",
  • "title": "string",
  • "created_by_user_id": "string",
  • "created_by_username": "string",
  • "created_by_email": "string",
  • "message_count": 0,
  • "queued_turn_count": 0,
  • "active_turn_count": 0,
  • "claim_state": "string",
  • "claim_holder_user_id": "string",
  • "claim_holder_username": "string",
  • "claim_holder_email": "string",
  • "handoff_to_user_id": "string",
  • "handoff_to_username": "string",
  • "handoff_note": "string",
  • "handoff_requested_at": "2019-08-24T14:15:22Z",
  • "last_message_at": "2019-08-24T14:15:22Z",
  • "last_activity_at": "2019-08-24T14:15:22Z",
  • "current_user_can_claim": false,
  • "current_user_can_post": false
}

Create Workroom Thread

Create a shared thread inside a workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
Request Body schema: application/json
required
title
required
string (Title) [ 1 .. 255 ] characters
Thread Key (string) or Thread Key (null) (Thread Key)
Opening Message (string) or Opening Message (null) (Opening Message)

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "thread_key": "string",
  • "opening_message": "string"
}

Response samples

Content type
application/json
{
  • "thread_key": "string",
  • "title": "string",
  • "created_by_user_id": "string",
  • "created_by_username": "string",
  • "created_by_email": "string",
  • "message_count": 0,
  • "queued_turn_count": 0,
  • "active_turn_count": 0,
  • "claim_state": "string",
  • "claim_holder_user_id": "string",
  • "claim_holder_username": "string",
  • "claim_holder_email": "string",
  • "handoff_to_user_id": "string",
  • "handoff_to_username": "string",
  • "handoff_note": "string",
  • "handoff_requested_at": "2019-08-24T14:15:22Z",
  • "last_message_at": "2019-08-24T14:15:22Z",
  • "last_activity_at": "2019-08-24T14:15:22Z",
  • "current_user_can_claim": false,
  • "current_user_can_post": false
}

List Workroom Thread Messages

List shared thread messages for the runtime shell.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters
query Parameters
limit
integer (Limit) [ 1 .. 500 ]
Default: 200

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List Workroom Thread Messages

List shared thread messages for the runtime shell.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters
query Parameters
limit
integer (Limit) [ 1 .. 500 ]
Default: 200

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Post Workroom Thread Message

Post a coordination message into a shared workroom thread.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters
Request Body schema: application/json
required
content
required
string (Content) [ 1 .. 16384 ] characters

Responses

Request samples

Content type
application/json
{
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "thread_key": "string",
  • "author_user_id": "string",
  • "author_username": "string",
  • "author_email": "string",
  • "message_type": "string",
  • "content": "string",
  • "message_metadata": { },
  • "created_at": "2019-08-24T14:15:22Z"
}

Post Workroom Thread Message

Post a coordination message into a shared workroom thread.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters
Request Body schema: application/json
required
content
required
string (Content) [ 1 .. 16384 ] characters

Responses

Request samples

Content type
application/json
{
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "thread_key": "string",
  • "author_user_id": "string",
  • "author_username": "string",
  • "author_email": "string",
  • "message_type": "string",
  • "content": "string",
  • "message_metadata": { },
  • "created_at": "2019-08-24T14:15:22Z"
}

Request Workroom Thread Handoff

Request handoff of a shared thread to another collaborator.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters
Request Body schema: application/json
required
to_user_id
required
string (To User Id) [ 1 .. 255 ] characters
Note (string) or Note (null) (Note)

Responses

Request samples

Content type
application/json
{
  • "to_user_id": "string",
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "thread_key": "string",
  • "handoff_to_user_id": "string",
  • "handoff_to_username": "string",
  • "handoff_note": "string",
  • "handoff_requested_at": "2019-08-24T14:15:22Z"
}

Request Workroom Thread Handoff

Request handoff of a shared thread to another collaborator.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters
Request Body schema: application/json
required
to_user_id
required
string (To User Id) [ 1 .. 255 ] characters
Note (string) or Note (null) (Note)

Responses

Request samples

Content type
application/json
{
  • "to_user_id": "string",
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "thread_key": "string",
  • "handoff_to_user_id": "string",
  • "handoff_to_username": "string",
  • "handoff_note": "string",
  • "handoff_requested_at": "2019-08-24T14:15:22Z"
}

Acquire Workroom Thread Claim

Acquire serialized control of a shared thread.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters
Request Body schema: application/json
required
Prompt Excerpt (string) or Prompt Excerpt (null) (Prompt Excerpt)
Any of
<= 1024 characters
string (Prompt Excerpt) <= 1024 characters

Responses

Request samples

Content type
application/json
{
  • "prompt_excerpt": "string"
}

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "thread_key": "string",
  • "claim_state": "string",
  • "interaction_mode": "string",
  • "holder_user_id": "string",
  • "holder_username": "string",
  • "holder_email": "string",
  • "claimed_at": "2019-08-24T14:15:22Z",
  • "released_at": "2019-08-24T14:15:22Z",
  • "queued_turn_id": "a09681c4-46ab-4c63-90b6-1e262ed427f5",
  • "is_current_holder": false
}

Acquire Workroom Thread Claim

Acquire serialized control of a shared thread.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters
Request Body schema: application/json
required
Prompt Excerpt (string) or Prompt Excerpt (null) (Prompt Excerpt)
Any of
<= 1024 characters
string (Prompt Excerpt) <= 1024 characters

Responses

Request samples

Content type
application/json
{
  • "prompt_excerpt": "string"
}

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "thread_key": "string",
  • "claim_state": "string",
  • "interaction_mode": "string",
  • "holder_user_id": "string",
  • "holder_username": "string",
  • "holder_email": "string",
  • "claimed_at": "2019-08-24T14:15:22Z",
  • "released_at": "2019-08-24T14:15:22Z",
  • "queued_turn_id": "a09681c4-46ab-4c63-90b6-1e262ed427f5",
  • "is_current_holder": false
}

Release Workroom Thread Claim

Release serialized control of a shared thread.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "thread_key": "string",
  • "claim_state": "string",
  • "interaction_mode": "string",
  • "holder_user_id": "string",
  • "holder_username": "string",
  • "holder_email": "string",
  • "claimed_at": "2019-08-24T14:15:22Z",
  • "released_at": "2019-08-24T14:15:22Z",
  • "queued_turn_id": "a09681c4-46ab-4c63-90b6-1e262ed427f5",
  • "is_current_holder": false
}

Release Workroom Thread Claim

Release serialized control of a shared thread.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "thread_key": "string",
  • "claim_state": "string",
  • "interaction_mode": "string",
  • "holder_user_id": "string",
  • "holder_username": "string",
  • "holder_email": "string",
  • "claimed_at": "2019-08-24T14:15:22Z",
  • "released_at": "2019-08-24T14:15:22Z",
  • "queued_turn_id": "a09681c4-46ab-4c63-90b6-1e262ed427f5",
  • "is_current_holder": false
}

List Workroom Thread Turns

List queued and active serialized turns for a thread.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters
query Parameters
limit
integer (Limit) [ 1 .. 200 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List Workroom Thread Turns

List queued and active serialized turns for a thread.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters
query Parameters
limit
integer (Limit) [ 1 .. 200 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Enqueue Workroom Thread Turn

Request an agent-capable turn in a serialized shared thread.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters
Request Body schema: application/json
required
prompt
required
string (Prompt) [ 1 .. 16384 ] characters
Connector Key (string) or Connector Key (null) (Connector Key)

Responses

Request samples

Content type
application/json
{
  • "prompt": "string",
  • "connector_key": "string"
}

Response samples

Content type
application/json
{
  • "turn": {
    },
  • "claim": {
    },
  • "credential_resolution": {
    },
  • "interaction_mode": "string"
}

Enqueue Workroom Thread Turn

Request an agent-capable turn in a serialized shared thread.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters
Request Body schema: application/json
required
prompt
required
string (Prompt) [ 1 .. 16384 ] characters
Connector Key (string) or Connector Key (null) (Connector Key)

Responses

Request samples

Content type
application/json
{
  • "prompt": "string",
  • "connector_key": "string"
}

Response samples

Content type
application/json
{
  • "turn": {
    },
  • "claim": {
    },
  • "credential_resolution": {
    },
  • "interaction_mode": "string"
}

Complete Workroom Thread Turn

Complete the active turn and promote the next queued collaborator.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
turn_id
required
string <uuid> (Turn Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters
Request Body schema: application/json
required
Completion Note (string) or Completion Note (null) (Completion Note)
Any of
<= 2048 characters
string (Completion Note) <= 2048 characters

Responses

Request samples

Content type
application/json
{
  • "completion_note": "string"
}

Response samples

Content type
application/json
{
  • "completed_turn": {
    },
  • "promoted_turn": {
    },
  • "claim": {
    }
}

Complete Workroom Thread Turn

Complete the active turn and promote the next queued collaborator.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
turn_id
required
string <uuid> (Turn Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters
Request Body schema: application/json
required
Completion Note (string) or Completion Note (null) (Completion Note)
Any of
<= 2048 characters
string (Completion Note) <= 2048 characters

Responses

Request samples

Content type
application/json
{
  • "completion_note": "string"
}

Response samples

Content type
application/json
{
  • "completed_turn": {
    },
  • "promoted_turn": {
    },
  • "claim": {
    }
}

Resolve Workroom Thread Credential Posture

Resolve credential posture for the acting user inside a shared thread.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters
query Parameters
connector_key
required
string (Connector Key) [ 1 .. 255 ] characters

Responses

Response samples

Content type
application/json
{
  • "connector_key": "string",
  • "resolution_state": "string",
  • "credential_source": "string",
  • "credential_path": "user",
  • "credential_outcome": "allowed",
  • "credential_requirement_source": "user",
  • "credential_owner_user_id": "string",
  • "credential_owner_username": "string",
  • "credential_owner_email": "string",
  • "explanation": "string"
}

Resolve Workroom Thread Credential Posture

Resolve credential posture for the acting user inside a shared thread.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
thread_key
required
string (Thread Key) [ 1 .. 255 ] characters
query Parameters
connector_key
required
string (Connector Key) [ 1 .. 255 ] characters

Responses

Response samples

Content type
application/json
{
  • "connector_key": "string",
  • "resolution_state": "string",
  • "credential_source": "string",
  • "credential_path": "user",
  • "credential_outcome": "allowed",
  • "credential_requirement_source": "user",
  • "credential_owner_user_id": "string",
  • "credential_owner_username": "string",
  • "credential_owner_email": "string",
  • "explanation": "string"
}

List Workroom Credential Registrations

List visible credential registrations for a workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List Workroom Credential Registrations

List visible credential registrations for a workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Upsert Workroom Credential Registration

Register or update a visible workroom credential posture.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
Request Body schema: application/json
required
connector_key
required
string (Connector Key) [ 1 .. 255 ] characters
registration_type
string (Registration Type)
Default: "personal"
Enum: "personal" "service_account"
label
required
string (Label) [ 1 .. 255 ] characters
Registration Metadata (object) or Registration Metadata (null) (Registration Metadata)

Responses

Request samples

Content type
application/json
{
  • "connector_key": "string",
  • "registration_type": "personal",
  • "label": "string",
  • "registration_metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connector_key": "string",
  • "registration_type": "string",
  • "owner_user_id": "string",
  • "owner_username": "string",
  • "owner_email": "string",
  • "label": "string",
  • "registration_metadata": { },
  • "created_by_user_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "revoked_at": "2019-08-24T14:15:22Z"
}

Upsert Workroom Credential Registration

Register or update a visible workroom credential posture.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
Request Body schema: application/json
required
connector_key
required
string (Connector Key) [ 1 .. 255 ] characters
registration_type
string (Registration Type)
Default: "personal"
Enum: "personal" "service_account"
label
required
string (Label) [ 1 .. 255 ] characters
Registration Metadata (object) or Registration Metadata (null) (Registration Metadata)

Responses

Request samples

Content type
application/json
{
  • "connector_key": "string",
  • "registration_type": "personal",
  • "label": "string",
  • "registration_metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connector_key": "string",
  • "registration_type": "string",
  • "owner_user_id": "string",
  • "owner_username": "string",
  • "owner_email": "string",
  • "label": "string",
  • "registration_metadata": { },
  • "created_by_user_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "revoked_at": "2019-08-24T14:15:22Z"
}

Remove Workroom Credential Registration

Revoke a visible workroom credential posture.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
registration_id
required
string <uuid> (Registration Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Remove Workroom Credential Registration

Revoke a visible workroom credential posture.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
registration_id
required
string <uuid> (Registration Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

List Workroom Credential Consents

List active credential reuse consents for a workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List Workroom Credential Consents

List active credential reuse consents for a workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Grant Workroom Credential Consent

Grant credential fallback consent inside a workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
Request Body schema: application/json
required
connector_key
required
string (Connector Key) [ 1 .. 255 ] characters
grantee_user_id
required
string (Grantee User Id) [ 1 .. 255 ] characters
Attestation Note (string) or Attestation Note (null) (Attestation Note)

Responses

Request samples

Content type
application/json
{
  • "connector_key": "string",
  • "grantee_user_id": "string",
  • "attestation_note": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connector_key": "string",
  • "grantor_user_id": "string",
  • "grantor_username": "string",
  • "grantor_email": "string",
  • "grantee_user_id": "string",
  • "grantee_username": "string",
  • "grantee_email": "string",
  • "consent_state": "string",
  • "attestation_note": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "revoked_at": "2019-08-24T14:15:22Z"
}

Grant Workroom Credential Consent

Grant credential fallback consent inside a workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
Request Body schema: application/json
required
connector_key
required
string (Connector Key) [ 1 .. 255 ] characters
grantee_user_id
required
string (Grantee User Id) [ 1 .. 255 ] characters
Attestation Note (string) or Attestation Note (null) (Attestation Note)

Responses

Request samples

Content type
application/json
{
  • "connector_key": "string",
  • "grantee_user_id": "string",
  • "attestation_note": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connector_key": "string",
  • "grantor_user_id": "string",
  • "grantor_username": "string",
  • "grantor_email": "string",
  • "grantee_user_id": "string",
  • "grantee_username": "string",
  • "grantee_email": "string",
  • "consent_state": "string",
  • "attestation_note": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "revoked_at": "2019-08-24T14:15:22Z"
}

Revoke Workroom Credential Consent

Revoke a workroom credential fallback consent.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
consent_id
required
string <uuid> (Consent Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Revoke Workroom Credential Consent

Revoke a workroom credential fallback consent.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
consent_id
required
string <uuid> (Consent Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

List Workroom Role History

List durable workroom role history for audit and turnover review.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
query Parameters
limit
integer (Limit) [ 1 .. 500 ]
Default: 200

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List Workroom Role History

List durable workroom role history for audit and turnover review.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
query Parameters
limit
integer (Limit) [ 1 .. 500 ]
Default: 200

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Lookup Workroom Member User

Resolve a platform user by email for the workroom invite flow.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
query Parameters
email
required
string (Email) [ 3 .. 320 ] characters

Responses

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "username": "string",
  • "email": "string"
}

Lookup Workroom Member User

Resolve a platform user by email for the workroom invite flow.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
query Parameters
email
required
string (Email) [ 3 .. 320 ] characters

Responses

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "username": "string",
  • "email": "string"
}

Update Workroom Member Role

Update the role of an existing workroom member.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
member_user_id
required
string (Member User Id)
Request Body schema: application/json
required
role
required
string (WorkroomRole)
Enum: "owner" "editor" "viewer"

Canonical workroom member roles for D180 sharing.

Responses

Request samples

Content type
application/json
{
  • "role": "owner"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "tenant_id": "string",
  • "user_id": "string",
  • "role": "string",
  • "invited_by_user_id": "string",
  • "active": true,
  • "joined_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "removed_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "email": "string",
  • "active_session_count": 0,
  • "is_primary_owner": false
}

Update Workroom Member Role

Update the role of an existing workroom member.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
member_user_id
required
string (Member User Id)
Request Body schema: application/json
required
role
required
string (WorkroomRole)
Enum: "owner" "editor" "viewer"

Canonical workroom member roles for D180 sharing.

Responses

Request samples

Content type
application/json
{
  • "role": "owner"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "tenant_id": "string",
  • "user_id": "string",
  • "role": "string",
  • "invited_by_user_id": "string",
  • "active": true,
  • "joined_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "removed_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "email": "string",
  • "active_session_count": 0,
  • "is_primary_owner": false
}

Remove Workroom Member

Remove a workroom member.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
member_user_id
required
string (Member User Id)
query Parameters
confirm_active_sessions
boolean (Confirm Active Sessions)
Default: false

Confirm that any active workroom sessions for the member should be terminated

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "tenant_id": "string",
  • "user_id": "string",
  • "role": "string",
  • "invited_by_user_id": "string",
  • "active": true,
  • "joined_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "removed_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "email": "string",
  • "active_session_count": 0,
  • "is_primary_owner": false
}

Remove Workroom Member

Remove a workroom member.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
member_user_id
required
string (Member User Id)
query Parameters
confirm_active_sessions
boolean (Confirm Active Sessions)
Default: false

Confirm that any active workroom sessions for the member should be terminated

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "tenant_id": "string",
  • "user_id": "string",
  • "role": "string",
  • "invited_by_user_id": "string",
  • "active": true,
  • "joined_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "removed_at": "2019-08-24T14:15:22Z",
  • "username": "string",
  • "email": "string",
  • "active_session_count": 0,
  • "is_primary_owner": false
}

Transfer Workroom Ownership

Transfer workroom ownership to another active member.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
Request Body schema: application/json
required
user_id
required
string (User Id) non-empty
keep_previous_owner
boolean (Keep Previous Owner)
Default: false
previous_owner_role
string (WorkroomRole)
Default: "editor"
Enum: "owner" "editor" "viewer"

Canonical workroom member roles for D180 sharing.

Attestation Note (string) or Attestation Note (null) (Attestation Note)

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "keep_previous_owner": false,
  • "previous_owner_role": "owner",
  • "attestation_note": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "string",
  • "owner_user_id": "string",
  • "name": "string",
  • "type": "string",
  • "description": "string",
  • "labels": [
    ],
  • "classification": "string",
  • "attributes": { },
  • "scg_references": [
    ],
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "member_count": 1,
  • "membership_role": "string",
  • "is_owner": true,
  • "is_shared": false,
  • "owner_username": "string",
  • "owner_email": "string"
}

Transfer Workroom Ownership

Transfer workroom ownership to another active member.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
Request Body schema: application/json
required
user_id
required
string (User Id) non-empty
keep_previous_owner
boolean (Keep Previous Owner)
Default: false
previous_owner_role
string (WorkroomRole)
Default: "editor"
Enum: "owner" "editor" "viewer"

Canonical workroom member roles for D180 sharing.

Attestation Note (string) or Attestation Note (null) (Attestation Note)

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "keep_previous_owner": false,
  • "previous_owner_role": "owner",
  • "attestation_note": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "string",
  • "owner_user_id": "string",
  • "name": "string",
  • "type": "string",
  • "description": "string",
  • "labels": [
    ],
  • "classification": "string",
  • "attributes": { },
  • "scg_references": [
    ],
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "member_count": 1,
  • "membership_role": "string",
  • "is_owner": true,
  • "is_shared": false,
  • "owner_username": "string",
  • "owner_email": "string"
}

Get Workroom Lifecycle Summary

Get lifecycle, resource, and retention summary for a visible workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "status": "string",
  • "workroom_type": "string",
  • "storage_consumed_bytes": 0,
  • "compute_resource_count": 0,
  • "app_deployment_count": 0,
  • "extension_count": 0,
  • "data_source_count": 0,
  • "catalog_entry_count": 0,
  • "active_member_count": 0,
  • "active_session_count": 0,
  • "ingestion_history_start": "2019-08-24T14:15:22Z",
  • "ingestion_history_end": "2019-08-24T14:15:22Z",
  • "ingestion_error_count": 0,
  • "retention_policy": "string",
  • "retention_detail": "string",
  • "retention_cleanup_at": "2019-08-24T14:15:22Z"
}

Get Workroom Lifecycle Summary

Get lifecycle, resource, and retention summary for a visible workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "status": "string",
  • "workroom_type": "string",
  • "storage_consumed_bytes": 0,
  • "compute_resource_count": 0,
  • "app_deployment_count": 0,
  • "extension_count": 0,
  • "data_source_count": 0,
  • "catalog_entry_count": 0,
  • "active_member_count": 0,
  • "active_session_count": 0,
  • "ingestion_history_start": "2019-08-24T14:15:22Z",
  • "ingestion_history_end": "2019-08-24T14:15:22Z",
  • "ingestion_error_count": 0,
  • "retention_policy": "string",
  • "retention_detail": "string",
  • "retention_cleanup_at": "2019-08-24T14:15:22Z"
}

Get Workroom Delete Preview

Preview the delete impact for an owner-managed workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "workroom_name": "string",
  • "active_session_count": 0,
  • "members_losing_access": [
    ],
  • "impact_items": [
    ],
  • "export_available": true
}

Get Workroom Delete Preview

Preview the delete impact for an owner-managed workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "workroom_name": "string",
  • "active_session_count": 0,
  • "members_losing_access": [
    ],
  • "impact_items": [
    ],
  • "export_available": true
}

Archive Workroom

Archive a workroom (makes it read-only).

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "string",
  • "owner_user_id": "string",
  • "name": "string",
  • "type": "string",
  • "description": "string",
  • "labels": [
    ],
  • "classification": "string",
  • "attributes": { },
  • "scg_references": [
    ],
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "member_count": 1,
  • "membership_role": "string",
  • "is_owner": true,
  • "is_shared": false,
  • "owner_username": "string",
  • "owner_email": "string"
}

Archive Workroom

Archive a workroom (makes it read-only).

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "string",
  • "owner_user_id": "string",
  • "name": "string",
  • "type": "string",
  • "description": "string",
  • "labels": [
    ],
  • "classification": "string",
  • "attributes": { },
  • "scg_references": [
    ],
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "member_count": 1,
  • "membership_role": "string",
  • "is_owner": true,
  • "is_shared": false,
  • "owner_username": "string",
  • "owner_email": "string"
}

Restore Workroom

Restore an archived workroom to active state.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "string",
  • "owner_user_id": "string",
  • "name": "string",
  • "type": "string",
  • "description": "string",
  • "labels": [
    ],
  • "classification": "string",
  • "attributes": { },
  • "scg_references": [
    ],
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "member_count": 1,
  • "membership_role": "string",
  • "is_owner": true,
  • "is_shared": false,
  • "owner_username": "string",
  • "owner_email": "string"
}

Restore Workroom

Restore an archived workroom to active state.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "string",
  • "owner_user_id": "string",
  • "name": "string",
  • "type": "string",
  • "description": "string",
  • "labels": [
    ],
  • "classification": "string",
  • "attributes": { },
  • "scg_references": [
    ],
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "deleted_at": "2019-08-24T14:15:22Z",
  • "member_count": 1,
  • "membership_role": "string",
  • "is_owner": true,
  • "is_shared": false,
  • "owner_username": "string",
  • "owner_email": "string"
}

Get Export Manifest

Get categorized list of workroom contents with export eligibility.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "items": [
    ]
}

Get Export Manifest

Get categorized list of workroom contents with export eligibility.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "items": [
    ]
}

Export Bundle

Export a downloadable ZIP bundle of workroom contents.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
null

Export Bundle

Export a downloadable ZIP bundle of workroom contents.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
null

Get Ingestion Summary

Get aggregated ingestion statistics for the workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "total_sources": 0,
  • "counts_by_source_type": {
    },
  • "date_range_start": "2019-08-24T14:15:22Z",
  • "date_range_end": "2019-08-24T14:15:22Z",
  • "error_count": 0,
  • "warning_count": 0,
  • "catalog_entries": 0
}

Get Ingestion Summary

Get aggregated ingestion statistics for the workroom.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "total_sources": 0,
  • "counts_by_source_type": {
    },
  • "date_range_start": "2019-08-24T14:15:22Z",
  • "date_range_end": "2019-08-24T14:15:22Z",
  • "error_count": 0,
  • "warning_count": 0,
  • "catalog_entries": 0
}

Get Workroom Runtime Bootstrap

Return shell bootstrap state for collaborative workroom runtime.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom": {
    },
  • "membership": {
    },
  • "shell_state": {
    },
  • "session": {
    },
  • "presence": [
    ],
  • "active_member_count": 0,
  • "active_session_count": 0,
  • "queued_turn_count": 0,
  • "claimed_thread_count": 0,
  • "active_handoff_count": 0,
  • "threads": [
    ],
  • "recent_events": [
    ],
  • "shared_credentials_enabled": false,
  • "credential_registrations": [
    ],
  • "credential_consents": [
    ]
}

Get Workroom Runtime Bootstrap

Return shell bootstrap state for collaborative workroom runtime.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom": {
    },
  • "membership": {
    },
  • "shell_state": {
    },
  • "session": {
    },
  • "presence": [
    ],
  • "active_member_count": 0,
  • "active_session_count": 0,
  • "queued_turn_count": 0,
  • "claimed_thread_count": 0,
  • "active_handoff_count": 0,
  • "threads": [
    ],
  • "recent_events": [
    ],
  • "shared_credentials_enabled": false,
  • "credential_registrations": [
    ],
  • "credential_consents": [
    ]
}

Get Workroom Runtime Context

Return the authoritative runtime context contract for the shell.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "user_id": "string",
  • "effective_workroom_role": "string",
  • "workroom_lifecycle_state": "string",
  • "interaction_mode": "string",
  • "access_state": "active",
  • "can_edit": false,
  • "can_share": false,
  • "can_run_agents": false,
  • "read_only_reason": "string",
  • "status_banner": "string"
}

Get Workroom Runtime Context

Return the authoritative runtime context contract for the shell.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "user_id": "string",
  • "effective_workroom_role": "string",
  • "workroom_lifecycle_state": "string",
  • "interaction_mode": "string",
  • "access_state": "active",
  • "can_edit": false,
  • "can_share": false,
  • "can_run_agents": false,
  • "read_only_reason": "string",
  • "status_banner": "string"
}

Stream Workroom Presence

Stream presence snapshots for the workroom members panel.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
null

Stream Workroom Presence

Stream presence snapshots for the workroom members panel.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
null

Heartbeat Workroom Session

Record a runtime heartbeat for the caller's currently bound workroom session.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
Request Body schema: application/json
Any of
session_state
string (WorkroomRuntimeSessionState)
Default: "active"
Enum: "active" "idle" "disconnected" "terminated"

Live runtime states for a workroom-bound session.

Focused Thread Key (string) or Focused Thread Key (null) (Focused Thread Key)
Client Metadata (object) or Client Metadata (null) (Client Metadata)

Responses

Request samples

Content type
application/json
Example
{
  • "session_state": "active",
  • "focused_thread_key": "string",
  • "client_metadata": { }
}

Response samples

Content type
application/json
{
  • "session": {
    },
  • "active_member_count": 0,
  • "active_session_count": 0,
  • "presence": [
    ]
}

Heartbeat Workroom Session

Record a runtime heartbeat for the caller's currently bound workroom session.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)
Request Body schema: application/json
Any of
session_state
string (WorkroomRuntimeSessionState)
Default: "active"
Enum: "active" "idle" "disconnected" "terminated"

Live runtime states for a workroom-bound session.

Focused Thread Key (string) or Focused Thread Key (null) (Focused Thread Key)
Client Metadata (object) or Client Metadata (null) (Client Metadata)

Responses

Request samples

Content type
application/json
Example
{
  • "session_state": "active",
  • "focused_thread_key": "string",
  • "client_metadata": { }
}

Response samples

Content type
application/json
{
  • "session": {
    },
  • "active_member_count": 0,
  • "active_session_count": 0,
  • "presence": [
    ]
}

Enter Workroom

Bind the calling user's session to a workroom.

Re-mints the JWT with a workroom_id claim (Lite/SAML) or updates session metadata (Keycloak). One user, one workroom, one token.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "access_token": "string",
  • "expires_in": 0,
  • "message": "Workroom session bound"
}

Enter Workroom

Bind the calling user's session to a workroom.

Re-mints the JWT with a workroom_id claim (Lite/SAML) or updates session metadata (Keycloak). One user, one workroom, one token.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "access_token": "string",
  • "expires_in": 0,
  • "message": "Workroom session bound"
}

Leave Workroom

Unbind the calling user from their current workroom.

Returns the session to no-workroom scope.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
Any of
Expected Workroom Id (string) or Expected Workroom Id (null) (Expected Workroom Id)

If provided, the leave only succeeds when the caller is still bound to this workroom.

Any of
string <uuid> (Expected Workroom Id)

If provided, the leave only succeeds when the caller is still bound to this workroom.

Responses

Request samples

Content type
application/json
Example
{
  • "expected_workroom_id": "3f0ca204-d45c-4245-90f1-3c4ea13a1b20"
}

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "access_token": "string",
  • "expires_in": 0,
  • "message": "Returned to no-workroom scope"
}

Leave Workroom

Unbind the calling user from their current workroom.

Returns the session to no-workroom scope.

Authorizations:
BearerAuthOAuth2Login
Request Body schema: application/json
Any of
Expected Workroom Id (string) or Expected Workroom Id (null) (Expected Workroom Id)

If provided, the leave only succeeds when the caller is still bound to this workroom.

Any of
string <uuid> (Expected Workroom Id)

If provided, the leave only succeeds when the caller is still bound to this workroom.

Responses

Request samples

Content type
application/json
Example
{
  • "expected_workroom_id": "3f0ca204-d45c-4245-90f1-3c4ea13a1b20"
}

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "access_token": "string",
  • "expires_in": 0,
  • "message": "Returned to no-workroom scope"
}

admin-workrooms

Admin List Workrooms

List all workrooms across all users with resolved owner identity (admin only).

Authorizations:
BearerAuthOAuth2Login
query Parameters
include_deleted
boolean (Include Deleted)
Default: false

Include deleted/purging workrooms in response

skip
integer (Skip) >= 0
Default: 0

Number of records to skip

limit
integer (Limit) [ 1 .. 1000 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Admin List Workrooms

List all workrooms across all users with resolved owner identity (admin only).

Authorizations:
BearerAuthOAuth2Login
query Parameters
include_deleted
boolean (Include Deleted)
Default: false

Include deleted/purging workrooms in response

skip
integer (Skip) >= 0
Default: 0

Number of records to skip

limit
integer (Limit) [ 1 .. 1000 ]
Default: 100

Max records to return

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Admin Delete Workroom

Admin delete — purges any workroom regardless of owner.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "status": "string",
  • "message": "string"
}

Admin Delete Workroom

Admin delete — purges any workroom regardless of owner.

Authorizations:
BearerAuthOAuth2Login
path Parameters
workroom_id
required
string <uuid> (Workroom Id)

Responses

Response samples

Content type
application/json
{
  • "workroom_id": "af729e58-bdc6-4b07-b43f-d9efa9e158a4",
  • "status": "string",
  • "message": "string"
}

node

Node Status

Get node status - open endpoint for health checks.

Responses

Response samples

Content type
application/json
{
  • "node_id": "string",
  • "status": "string",
  • "message": "string"
}

Node Id

Get node ID - requires authentication.

Authorizations:
BearerAuthOAuth2Login

Responses

Response samples

Content type
application/json
"string"