Skip to main content
API docs by Redocly

FastAPI (0.9.3)

Download OpenAPI specification:Download

health

Ping

Simple ping endpoint for liveness testing.

Responses

Response samples

Content type
application/json
null

Whoami

Return current user information from headers.

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.

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.

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

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

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

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

Responses

Response samples

Content type
application/json
null

List Idps

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

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get User Detail

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",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Update Local

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",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Delete Local

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",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Create Local

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",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Reset Password

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",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Change My Password

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

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

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

Create Pat

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

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": 0,
  • "scope": "string",
  • "aud": "string"
}

Response samples

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

List My Pats

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

Responses

Response samples

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

Revoke My Pat

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

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

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

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

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

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

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

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.

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.

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

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

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

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

Responses

Response samples

Content type
application/json
null

List Idps

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

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get User Detail

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",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Update Local

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",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Delete Local

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",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Create Local

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",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Reset Password

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",
  • "full_name": "string",
  • "name": "string",
  • "is_superuser": false,
  • "created_at": "string",
  • "updated_at": "string"
}

Change My Password

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

ForwardAuth validation endpoint for Traefik. Refactored for clarity: bypass → token → validate → claims→user → RBAC → response

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

ForwardAuth validation endpoint for Traefik. Refactored for clarity: bypass → token → validate → claims→user → RBAC → response

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

ForwardAuth validation endpoint for Traefik. Refactored for clarity: bypass → token → validate → claims→user → RBAC → response

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

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

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

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

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

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

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

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

header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
required
object (SubjectModel)
relation
required
string (Relation) ^(owner|editor|viewer|member|operator|mission...
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

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

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

Request Body schema: application/json
required
required
object (SubjectModel)
relation
required
string (Relation) ^(owner|editor|viewer|member|operator|mission...
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 }

Responses

Response samples

Content type
application/json
{ }

Cleanup Stale Deployments

Manually clean up stale deployment flags in etcd.

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 }

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}

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.

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",
  • "created_timestamp": "2019-08-24T14:15:22Z",
  • "modified_timestamp": "2019-08-24T14:15:22Z",
  • "files_being_downloaded": [ ]
}

Delete Model Endpoint

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

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.

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",
  • "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.

query Parameters
load_files
boolean (Load Files)
Default: false

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Model File Endpoint

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.

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"
}

Search Models

Search for models based on a given search request.

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

Returns: List[Model]: A list of models that match the search criteria.

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
}

List Model Files

List all model files.

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

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.

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"
}

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.

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

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)

Responses

Request samples

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

Response samples

Content type
application/json
{ }

Create Model Configuration

Create a new model configuration.

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.

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.

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.

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.

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

Responses

Response samples

Content type
application/json
null

Update Model Configuration

Update a model configuration by its ID.

path Parameters
model_config_id
required
string <uuid> (Model Config Id)
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.

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.

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.

Responses

Response samples

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

Cancel Model Download Endpoint

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

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

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)

Responses

Request samples

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

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

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.

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.

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.

Responses

Response samples

Content type
application/json
{ }

config

Get Routing Config

Responses

Response samples

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

Get Routing Config

Responses

Response samples

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

Patch Routing Config

Request Body schema: application/json
required
Base Host (string) or Base Host (null) (Base Host)
Service Prefixes (object) or Service Prefixes (null) (Service Prefixes)
Enabled Services (object) or Enabled Services (null) (Enabled Services)

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

Request Body schema: application/json
required
Base Host (string) or Base Host (null) (Base Host)
Service Prefixes (object) or Service Prefixes (null) (Service Prefixes)
Enabled Services (object) or Enabled Services (null) (Enabled Services)

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"
}

serving

Start Ray

Start Ray with the given parameters. If Ray is already running, a RayServiceException is raised.

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

Get Status

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

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.

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)

Not user-settable (ignored); The VRAM allocation, in bytes of vram for each copy of the deployed model

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

Not user-settable (ignored); The GPU allocation, as a percentage of the the total VRAM available on the highest vram node, for ray serve allocation

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

Responses

Request samples

Content type
application/json
{
  • "m_id": "9fa8614b-5eb2-4338-b373-8a5898e84e27",
  • "m_file_id": "4ac4c186-075b-4681-9464-7d9e843ec833",
  • "m_config_id": "3332a42e-73e6-4c01-9873-ee2c21c5e45a",
  • "engine_name": "string",
  • "duration": 0,
  • "min_copies": 1,
  • "starting_copies": 1,
  • "max_copies": 0,
  • "location": "string",
  • "lb_port": 0,
  • "autoscaling": false,
  • "force_cpu": false,
  • "node_resource_type": "string",
  • "max_concurrent_requests": 0,
  • "vram_allocation": 0,
  • "gpu_allocation": 0,
  • "active_req_per_replica": 20,
  • "m_version": "string",
  • "engine": "vllm",
  • "container": "kamiwaza"
}

Response samples

Content type
application/json
{ }

Deploy Model

Asynchronously deploy a model based on the provided deployment request.

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

Returns: Union[UUID, bool]: The UUID of the deployed model or False if deployment failed.

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)

Not user-settable (ignored); The VRAM allocation, in bytes of vram for each copy of the deployed model

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

Not user-settable (ignored); The GPU allocation, as a percentage of the the total VRAM available on the highest vram node, for ray serve allocation

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

Responses

Request samples

Content type
application/json
{
  • "m_id": "9fa8614b-5eb2-4338-b373-8a5898e84e27",
  • "m_file_id": "4ac4c186-075b-4681-9464-7d9e843ec833",
  • "m_config_id": "3332a42e-73e6-4c01-9873-ee2c21c5e45a",
  • "engine_name": "string",
  • "duration": 0,
  • "min_copies": 1,
  • "starting_copies": 1,
  • "max_copies": 0,
  • "location": "string",
  • "lb_port": 0,
  • "autoscaling": false,
  • "force_cpu": false,
  • "node_resource_type": "string",
  • "max_concurrent_requests": 0,
  • "vram_allocation": 0,
  • "gpu_allocation": 0,
  • "active_req_per_replica": 20,
  • "m_version": "string",
  • "engine": "vllm",
  • "container": "kamiwaza"
}

Response samples

Content type
application/json
true

List Deployments

List all model deployments or filter by model_id if provided.

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.

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

query Parameters
Model Id (string) or Model Id (null) (Model Id)

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.

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

Responses

Response samples

Content type
application/json
{
  • "m_id": "9fa8614b-5eb2-4338-b373-8a5898e84e27",
  • "m_file_id": "4ac4c186-075b-4681-9464-7d9e843ec833",
  • "m_config_id": "3332a42e-73e6-4c01-9873-ee2c21c5e45a",
  • "engine_name": "string",
  • "duration": 0,
  • "min_copies": 1,
  • "starting_copies": 1,
  • "max_copies": 0,
  • "location": "string",
  • "lb_port": 0,
  • "autoscaling": false,
  • "force_cpu": false,
  • "node_resource_type": "string",
  • "max_concurrent_requests": 0,
  • "vram_allocation": 0,
  • "gpu_allocation": 0,
  • "active_req_per_replica": 20,
  • "m_version": "string",
  • "engine": "vllm",
  • "container": "kamiwaza",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "requested_at": "2019-08-24T14:15:22Z",
  • "deployed_at": "2019-08-24T14:15:22Z",
  • "serve_path": "string",
  • "access_path_prefix": "string",
  • "access_path": "string",
  • "single_node_mode": false,
  • "status": "UNINITIALIZED",
  • "last_error_code": "string",
  • "last_error_message": "string",
  • "last_error_at": "2019-08-24T14:15:22Z",
  • "health_details": { },
  • "instances": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "gpu_memory_utilization": 0,
  • "tensor_parallel_size": 0,
  • "m_name": "string",
  • "m_config_name": "string",
  • "host_ip": "string"
}

Stop Deployment

Stop a model deployment.

Args: deployment_id (UUID): The ID of the deployment to stop. force (Optional[bool]): Whether to force stop the deployment. Defaults to False.

Returns: bool: True if the deployment was successfully stopped, otherwise raises an HTTPException.

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.

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.

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.

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.

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.

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.

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.).

path Parameters
engine_type
required
string (Engine Type)

Responses

Response samples

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

vectordb

Create Vectordb

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

The name of the vectordb instance to register

engine
required
string (Engine)

The engine of the vectordb instance, eg Milvus

description
required
string (Description)

The description of the vectordb instance

host
required
string (Host)

The host of the vectordb instance

port
required
integer (Port)

The port of the vectordb instance

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "engine": "string",
  • "description": "string",
  • "host": "string",
  • "port": 0
}

Response samples

Content type
application/json
null

Get Vectordbs

Retrieve all VectorDB instances, optionally filtered by engine.

:param engine: Optional engine type to filter the VectorDB instances. :return: List of VectorDB instances.

query Parameters
engine
string (Engine)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Collections

List all collections in the vector database.

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get Vectordb

Get a specific VectorDB instance.

path Parameters
vectordb_id
required
string (Vectordb Id)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "engine": "string",
  • "description": "string",
  • "host": "string",
  • "port": 0,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "modified_at": "2019-08-24T14:15:22Z"
}

Remove Vectordb

Remove a specific VectorDB instance.

path Parameters
vectordb_id
required
string (Vectordb Id)

Responses

Response samples

Content type
application/json
null

Insert Vectors

Request Body schema: application/json
required
collection_name
required
string (Collection Name)
vectors
required
Array of numbers (Vectors) [ items ]
required
Array of objects (Metadata)
dimensions
required
integer (Dimensions)
Array of Field List (items) or Field List (null) (Field List)

Responses

Request samples

Content type
application/json
{
  • "collection_name": "string",
  • "vectors": [
    ],
  • "metadata": [
    ],
  • "dimensions": 0,
  • "field_list": [
    ]
}

Response samples

Content type
application/json
null

Search Vectors

Request Body schema: application/json
required
collection_name
required
string (Collection Name)
query_vectors
required
Array of numbers (Query Vectors) [ items ]
anns_field
string (Anns Field)
Default: "embedding"
Search Params (object) or Search Params (null) (Search Params)
limit
integer (Limit)
Default: 100
Array of Output Fields (strings) or Output Fields (null) (Output Fields)

Responses

Request samples

Content type
application/json
{
  • "collection_name": "string",
  • "query_vectors": [
    ],
  • "anns_field": "embedding",
  • "search_params": { },
  • "limit": 100,
  • "output_fields": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Drop Collection

Drop a collection from the vector database.

path Parameters
collection_name
required
string (Collection Name)

Responses

Response samples

Content type
application/json
null

catalog

Health Check

Simple health check endpoint.

Responses

Response samples

Content type
application/json
null

Health Check

Simple health check endpoint.

Responses

Response samples

Content type
application/json
null

Create Dataset

Create a new dataset.

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.

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.

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.

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)

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",
  • "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)

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",
  • "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.

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",
  • "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.

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",
  • "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.

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.

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)

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)

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.

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.

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

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)

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",
  • "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)

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",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Dataset

Update dataset by URN in path (BACKWARD COMPATIBLE).

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",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Dataset

Update dataset by URN in path (BACKWARD COMPATIBLE).

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",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Dataset

Delete dataset by URN in path (BACKWARD COMPATIBLE).

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).

path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

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

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)

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",
  • "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)

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",
  • "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)

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",
  • "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)

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",
  • "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)

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)

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

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

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

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

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 Container By Urn

Get container by URN using query parameter.

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",
  • "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.

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",
  • "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.

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",
  • "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.

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",
  • "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.

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.

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.

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.

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.

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.

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

Add Dataset To Container

Add a dataset to a container.

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.

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.

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.

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.

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.

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.

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.

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.

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",
  • "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.

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",
  • "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.

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",
  • "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.

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",
  • "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.

path Parameters
container_urn
required
string (Container Urn)

Responses

Response samples

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

Delete Container

Deletes a container.

path Parameters
container_urn
required
string (Container Urn)

Responses

Response samples

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

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)

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",
  • "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)

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",
  • "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)

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",
  • "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)

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",
  • "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)

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)

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

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

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)

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)

path Parameters
container_urn
required
string (Container Urn)
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
null

Create Secret

Create a new secret. Owner defaults if not provided.

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.

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

List secrets the requester has permission to see.

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

List secrets the requester has permission to see.

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).

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",
  • "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).

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",
  • "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).

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
{
  • "detail": [
    ]
}

Delete Secret By Urn

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

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
{
  • "detail": [
    ]
}

Get Secret

Get secret metadata by URN (requires permission).

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",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get Secret

Get secret metadata by URN (requires permission).

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",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Secret

Delete a secret by URN (requires permission).

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
{
  • "detail": [
    ]
}

Delete Secret

Delete a secret by URN (requires permission).

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
{
  • "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)

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",
  • "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)

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",
  • "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)

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
{
  • "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)

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
{
  • "detail": [
    ]
}

Catalog Service Root

Provides basic information about the catalog service.

Responses

Response samples

Content type
application/json
null

Catalog Service Root

Provides basic information about the catalog service.

Responses

Response samples

Content type
application/json
null

datasets

Create Dataset

Create a new dataset.

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.

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)

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",
  • "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.

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",
  • "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.

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)

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.

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

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)

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",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Dataset

Update dataset by URN in path (BACKWARD COMPATIBLE).

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",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Dataset

Delete dataset by URN in path (BACKWARD COMPATIBLE).

path Parameters
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

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

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)

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",
  • "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)

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",
  • "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)

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

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

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

containers

Get Container By Urn

Get container by URN using query parameter.

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",
  • "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.

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",
  • "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.

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.

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.

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

Add Dataset To Container

Add a dataset to a container.

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.

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.

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.

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.

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",
  • "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.

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",
  • "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.

path Parameters
container_urn
required
string (Container Urn)

Responses

Response samples

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

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)

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",
  • "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)

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",
  • "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)

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

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)

path Parameters
container_urn
required
string (Container Urn)
dataset_urn
required
string (Dataset Urn)

Responses

Response samples

Content type
application/json
null

secrets

Create Secret

Create a new secret. Owner defaults if not provided.

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

List secrets the requester has permission to see.

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).

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",
  • "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).

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
{
  • "detail": [
    ]
}

Get Secret

Get secret metadata by URN (requires permission).

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",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Secret

Delete a secret by URN (requires permission).

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
{
  • "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)

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",
  • "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)

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
{
  • "detail": [
    ]
}

prompts

Create Role

Create a new role.

:param role: PromptRoleCreate schema. :return: The created PromptRole model.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 embedding using specified model configuration

Request Body schema: application/json
required
text
required
string (Text)

Text to generate embedding for

model
required
string (Model)

Model name to use

provider_type
required
string (Provider Type)

Provider type (e.g., huggingface_embedding)

Device (string) or Device (null) (Device)

Device to use (cpu, cuda, mps)

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 embedding using specified model configuration

Request Body schema: application/json
required
text
required
string (Text)

Text to generate embedding for

model
required
string (Model)

Model name to use

provider_type
required
string (Provider Type)

Provider type (e.g., huggingface_embedding)

Device (string) or Device (null) (Device)

Device to use (cpu, cuda, mps)

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

Get embedding using specified model configuration

path Parameters
text
required
string (Text)
query Parameters
model
required
string (Model)

Model name

provider_type
required
string (Provider Type)

Provider type

Device (string) or Device (null) (Device)

Device

return_offset
boolean (Return Offset)
Default: false

Responses

Response samples

Content type
application/json
{
  • "embedding": [
    ],
  • "offset": 0
}

Get Embedding

Get embedding using specified model configuration

path Parameters
text
required
string (Text)
query Parameters
model
required
string (Model)

Model name

provider_type
required
string (Provider Type)

Provider type

Device (string) or Device (null) (Device)

Device

return_offset
boolean (Return Offset)
Default: false

Responses

Response samples

Content type
application/json
{
  • "embedding": [
    ],
  • "offset": 0
}

Chunk Text

Chunk text using specified model configuration

query Parameters
model
required
string (Model)

Model name to use

provider_type
required
string (Provider Type)

Provider type (e.g., huggingface_embedding)

Device (string) or Device (null) (Device)

Device to use (cpu, cuda, mps)

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 using specified model configuration

query Parameters
model
required
string (Model)

Model name to use

provider_type
required
string (Provider Type)

Provider type (e.g., huggingface_embedding)

Device (string) or Device (null) (Device)

Device to use (cpu, cuda, mps)

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 using specified model configuration

query Parameters
model
required
string (Model)

Model name to use

provider_type
required
string (Provider Type)

Provider type (e.g., huggingface_embedding)

Device (string) or Device (null) (Device)

Device to use (cpu, cuda, mps)

batch_size
integer (Batch Size)
Default: 64

Batch size for processing

Request Body schema: application/json
required
Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • [
    ]
]

Embed Chunks

Embed chunks using specified model configuration

query Parameters
model
required
string (Model)

Model name to use

provider_type
required
string (Provider Type)

Provider type (e.g., huggingface_embedding)

Device (string) or Device (null) (Device)

Device to use (cpu, cuda, mps)

batch_size
integer (Batch Size)
Default: 64

Batch size for processing

Request Body schema: application/json
required
Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • [
    ]
]

Get Providers

Get list of available embedding providers

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get Providers

Get list of available embedding providers

Responses

Response samples

Content type
application/json
[
  • "string"
]

Health Check

Health check for embedding service (public endpoint for load balancers)

Responses

Response samples

Content type
application/json
null

Health Check

Health check for embedding service (public endpoint for load balancers)

Responses

Response samples

Content type
application/json
null

cluster

Create Location

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.

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

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

query Parameters
Skip (integer) or Skip (null) (Skip)
Limit (integer) or Limit (null) (Limit)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Cluster

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"
}

Get Cluster

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"
}

List Clusters

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

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Nodes

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

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

query Parameters
Skip (integer) or Skip (null) (Skip)
Limit (integer) or Limit (null) (Limit)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Hardware

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.

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.

Returns: Dict[str, Any]: A dictionary containing cluster capabilities information.

Responses

Response samples

Content type
application/json
{ }

Attach Pairing

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

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.

Responses

Response samples

Content type
application/json
null

Cluster Get Hostname

Endpoint to provide the hostname to be tested by the client.

Responses

Response samples

Content type
application/json
null

Create Federation

Create a new cluster federation.

Args: federation: Federation creation data

Returns: Created ClusterFederation object

Request Body schema: application/json
required
remote_cluster_name
required
string (Remote Cluster Name)

Name of the remote cluster for display

required
Array of objects (Remote Ips)

List of remote IPs with primary flag

Preshared Key (string) or Preshared Key (null) (Preshared Key)

Pre-shared key for authentication, auto-generated if not provided

Callback Hostname (string) or Callback Hostname (null) (Callback Hostname)

Optional hostname/IP for remote cluster to use for callbacks

Responses

Request samples

Content type
application/json
{
  • "remote_cluster_name": "string",
  • "remote_ips": [
    ],
  • "preshared_key": "string",
  • "callback_hostname": "string"
}

Response samples

Content type
application/json
{
  • "remote_cluster_name": "string",
  • "remote_ips": [
    ],
  • "preshared_key": "string",
  • "callback_hostname": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "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"
}

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

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

path Parameters
federation_id
required
string <uuid> (Federation Id)

Responses

Response samples

Content type
application/json
{
  • "remote_cluster_name": "string",
  • "remote_ips": [
    ],
  • "preshared_key": "string",
  • "callback_hostname": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "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"
}

Update Federation

Update a cluster federation.

Args: federation_id: UUID of the federation updates: Dictionary of fields to update

Returns: Updated ClusterFederation object

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
{
  • "remote_cluster_name": "string",
  • "remote_ips": [
    ],
  • "preshared_key": "string",
  • "callback_hostname": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "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"
}

Delete Federation

Soft delete a cluster federation (mark as DELETED).

Args: federation_id: UUID of the federation

Returns: Success message

path Parameters
federation_id
required
string <uuid> (Federation Id)

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

path Parameters
federation_id
required
string <uuid> (Federation Id)

Responses

Response samples

Content type
application/json
{
  • "remote_cluster_name": "string",
  • "remote_ips": [
    ],
  • "preshared_key": "string",
  • "callback_hostname": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "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"
}

Handle Pair Federation

Handle incoming federation pairing request from remote cluster. This endpoint is called by remote clusters initiating pairing.

Args: request: FederationPairRequest from remote cluster

Returns: Response with local cluster ID

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

preshared_key
required
string (Preshared Key)

Pre-shared key for authentication

Responses

Request samples

Content type
application/json
{
  • "local_cluster_id": "1260b091-d4ae-49be-a02b-b44ea252bd7e",
  • "local_cluster_name": "string",
  • "local_ips": [
    ],
  • "preshared_key": "string"
}

Response samples

Content type
application/json
null

Handle Reciprocation

Handle incoming federation reciprocation from remote cluster. This endpoint is called by remote clusters acknowledging pairing.

Args: request: FederationReciprocateRequest from remote cluster

Returns: Success status

Request Body schema: application/json
required
remote_host
required
string (Remote Host)

Remote host address

local_host
required
string (Local Host)

Local host address

required
Remote Cluster Id (string) or Remote Cluster Id (string) (Remote Cluster Id)

Remote cluster ID

acknowledged
required
boolean (Acknowledged)

Acknowledgment status

Responses

Request samples

Content type
application/json
{
  • "remote_host": "string",
  • "local_host": "string",
  • "remote_cluster_id": "2e5a86d7-242f-4a38-9dcb-3cd98ca8c46e",
  • "acknowledged": true
}

Response samples

Content type
application/json
null

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

path Parameters
federation_id
required
string <uuid> (Federation Id)
query Parameters
force
boolean (Force)
Default: false

Responses

Response samples

Content type
application/json
null

Handle Disconnect Request

Handle incoming disconnect request from remote cluster. This endpoint is called by remote clusters initiating disconnect.

Args: request: FederationDisconnectRequest from remote cluster

Returns: Success status

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

Ping Federation

Health check a federated cluster.

Args: federation_id: UUID of the federation to ping

Returns: Ping status

path Parameters
federation_id
required
string <uuid> (Federation Id)

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

ingestion

Health

Responses

Response samples

Content type
application/json
null

Health

Responses

Response samples

Content type
application/json
null

Run Active

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

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

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

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

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

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

path Parameters
job_id
required
string (Job Id)

Responses

Response samples

Content type
application/json
null

Status

path Parameters
job_id
required
string (Job Id)

Responses

Response samples

Content type
application/json
null

List Connectors

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)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Create Connector

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

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

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

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

path Parameters
connector_id
required
string <uuid> (Connector Id)

Responses

Response samples

Content type
application/json
{
  • "status": "queued"
}

Create Document

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

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

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
}

dde-connectors

List Connectors

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)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

List Connectors

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)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Create Connector

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

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

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

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

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

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

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

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

path Parameters
connector_id
required
string <uuid> (Connector Id)

Responses

Response samples

Content type
application/json
{
  • "status": "queued"
}

Trigger Ingest

path Parameters
connector_id
required
string <uuid> (Connector Id)

Responses

Response samples

Content type
application/json
{
  • "status": "queued"
}

dde-documents

Create Document

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

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

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

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

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

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

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

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": {
    }
}

Get Retrieval Job

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

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

path Parameters
job_id
required
string <uuid> (Job Id)

Responses

Response samples

Content type
application/json
null

Stream Retrieval Job

path Parameters
job_id
required
string <uuid> (Job Id)

Responses

Response samples

Content type
application/json
null

news

Get News Quadrants

Get the structured news content in quadrant format.

Returns: NewsResponse: Object containing quadrant-structured news data

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

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

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

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.

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.

path Parameters
deployment_type
required
string (DeploymentType)
Enum: "vllm" "llamacpp" "mlx" "ampere" "app_garden" "tool_shed" "unknown"

Type of deployment

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.

path Parameters
deployment_type
required
string (DeploymentType)
Enum: "vllm" "llamacpp" "mlx" "ampere" "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.

path Parameters
deployment_type
required
string (DeploymentType)
Enum: "vllm" "llamacpp" "mlx" "ampere" "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.

path Parameters
deployment_type
required
string (DeploymentType)
Enum: "vllm" "llamacpp" "mlx" "ampere" "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
}

List Orphaned Logs

List all orphaned log files (deployments that no longer exist).

Responses

Response samples

Content type
application/json
{
  • "logs": [
    ],
  • "total_count": 0,
  • "orphaned_count": 0
}

Get Log Statistics

Get storage statistics for all logs.

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.

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.

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.

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.

path Parameters
engine_type
required
string (Engine Type)

Responses

Response samples

Content type
application/json
{
  • "logs": [
    ],
  • "total_count": 0,
  • "orphaned_count": 0
}

Logger Service

List All Deployment Logs

List all deployment logs across all services. This is the main endpoint for the unified logs viewer UI.

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.

path Parameters
deployment_type
required
string (DeploymentType)
Enum: "vllm" "llamacpp" "mlx" "ampere" "app_garden" "tool_shed" "unknown"

Type of deployment

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.

path Parameters
deployment_type
required
string (DeploymentType)
Enum: "vllm" "llamacpp" "mlx" "ampere" "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.

path Parameters
deployment_type
required
string (DeploymentType)
Enum: "vllm" "llamacpp" "mlx" "ampere" "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.

path Parameters
deployment_type
required
string (DeploymentType)
Enum: "vllm" "llamacpp" "mlx" "ampere" "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
}

List Orphaned Logs

List all orphaned log files (deployments that no longer exist).

Responses

Response samples

Content type
application/json
{
  • "logs": [
    ],
  • "total_count": 0,
  • "orphaned_count": 0
}

Get Log Statistics

Get storage statistics for all logs.

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.

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.

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.

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.

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.

Responses

Response samples

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

Deploy App

Deploy a new application.

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.

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
{
  • "name": "string",
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "min_copies": 1,
  • "starting_copies": 1,
  • "max_copies": 0,
  • "serve_path": "string",
  • "lb_port": 0,
  • "port_mappings": [
    ],
  • "runtime_resources_id": "5523ab73-0d21-4472-a248-f87deceba08f",
  • "env_vars": {
    },
  • "is_ephemeral_session": true,
  • "preferred_model_type": "string",
  • "fail_if_model_type_unavailable": false,
  • "preferred_model_name": "string",
  • "fail_if_model_name_unavailable": false
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "min_copies": 1,
  • "starting_copies": 1,
  • "max_copies": 0,
  • "serve_path": "string",
  • "lb_port": 0,
  • "port_mappings": [
    ],
  • "runtime_resources_id": "5523ab73-0d21-4472-a248-f87deceba08f",
  • "env_vars": {
    },
  • "is_ephemeral_session": false,
  • "preferred_model_type": "string",
  • "fail_if_model_type_unavailable": false,
  • "preferred_model_name": "string",
  • "fail_if_model_name_unavailable": false,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "requested_at": "2019-08-24T14:15:22Z",
  • "deployed_at": "2019-08-24T14:15:22Z",
  • "status": "UNINITIALIZED",
  • "instances": [
    ],
  • "access_path_prefix": "string",
  • "access_path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "compose_yml": "string",
  • "runtime_artifacts": { },
  • "owner_user_id": "string",
  • "owner_session_id": "string",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "purge_requested_at": "2019-08-24T14:15:22Z",
  • "image_status": { }
}

List Deployments

List all app deployments.

Returns: List[AppDeployment]: A list of all app deployments.

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.

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

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc",
  • "min_copies": 1,
  • "starting_copies": 1,
  • "max_copies": 0,
  • "serve_path": "string",
  • "lb_port": 0,
  • "port_mappings": [
    ],
  • "runtime_resources_id": "5523ab73-0d21-4472-a248-f87deceba08f",
  • "env_vars": {
    },
  • "is_ephemeral_session": false,
  • "preferred_model_type": "string",
  • "fail_if_model_type_unavailable": false,
  • "preferred_model_name": "string",
  • "fail_if_model_name_unavailable": false,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "requested_at": "2019-08-24T14:15:22Z",
  • "deployed_at": "2019-08-24T14:15:22Z",
  • "status": "UNINITIALIZED",
  • "instances": [
    ],
  • "access_path_prefix": "string",
  • "access_path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "compose_yml": "string",
  • "runtime_artifacts": { },
  • "owner_user_id": "string",
  • "owner_session_id": "string",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "purge_requested_at": "2019-08-24T14:15:22Z",
  • "image_status": { }
}

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.

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

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 app session token.

Token should be provided in one of:

  • Authorization header: "Bearer "
  • X-App-Session-Token header: ""
  • Request body: {"session_token": ""}

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "deployment_id": "6ef0ac85-9892-4664-a2a5-58bf2af5a8a6"
}

End App Session

End an app session token and purge the associated deployment.

Token should be provided in one of:

  • Authorization header: "Bearer "
  • X-App-Session-Token header: ""
  • Request body: {"session_token": "", "reason": "..."}
Request Body schema: application/json
Reason (string) or Reason (null) (Reason)

Optional reason for ending the session, used for audit logging.

Session Token (string) or Session Token (null) (Session Token)

Session token if not provided in X-Session-Token header.

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "session_token": "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.

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.

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.

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

Responses

Response samples

Content type
application/json
"string"

app_templates

List App Templates

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create App Template

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"
visibility
string (TemplateVisibility)
Default: "private"
Enum: "private" "team" "public"
compose_yml
required
string (Compose Yml)

Raw docker-compose YAML content

risk_tier
integer (RiskTier)
Default: 0
Enum: 0 1 2
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

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)
Default: "any"

Preferred model type: 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 URL for the template

Kamiwaza Version (string) or Kamiwaza Version (null) (Kamiwaza Version)

Kamiwaza version constraint (e.g., '>=0.7.0', '>=0.7.0,<0.9.0', '*')

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "version": "string",
  • "source_type": "kamiwaza",
  • "visibility": "private",
  • "compose_yml": "string",
  • "risk_tier": 0,
  • "validate_containers": false,
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "env_defaults": {
    },
  • "description": "string",
  • "category": "string",
  • "tags": [
    ],
  • "author": "string",
  • "license": "string",
  • "homepage": "string",
  • "image": "string",
  • "capabilities": [
    ],
  • "required_env_vars": [
    ],
  • "preferred_model_type": "any",
  • "fail_if_model_type_unavailable": false,
  • "preferred_model_name": "string",
  • "fail_if_model_name_unavailable": false,
  • "preview_image": "string",
  • "kamiwaza_version": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "version": "string",
  • "source_type": "kamiwaza",
  • "visibility": "private",
  • "compose_yml": "string",
  • "risk_tier": 0,
  • "validate_containers": false,
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "env_defaults": {
    },
  • "description": "string",
  • "category": "string",
  • "tags": [
    ],
  • "author": "string",
  • "license": "string",
  • "homepage": "string",
  • "image": "string",
  • "capabilities": [
    ],
  • "required_env_vars": [
    ],
  • "preferred_model_type": "any",
  • "fail_if_model_type_unavailable": false,
  • "preferred_model_name": "string",
  • "fail_if_model_name_unavailable": false,
  • "preview_image": "string",
  • "kamiwaza_version": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "verified": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get App Template

path Parameters
template_id
required
string <uuid> (Template Id)

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "version": "string",
  • "source_type": "kamiwaza",
  • "visibility": "private",
  • "compose_yml": "string",
  • "risk_tier": 0,
  • "validate_containers": false,
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "env_defaults": {
    },
  • "description": "string",
  • "category": "string",
  • "tags": [
    ],
  • "author": "string",
  • "license": "string",
  • "homepage": "string",
  • "image": "string",
  • "capabilities": [
    ],
  • "required_env_vars": [
    ],
  • "preferred_model_type": "any",
  • "fail_if_model_type_unavailable": false,
  • "preferred_model_name": "string",
  • "fail_if_model_name_unavailable": false,
  • "preview_image": "string",
  • "kamiwaza_version": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "verified": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Template

Update a template using API-provided payload data.

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
TemplateVisibility (string) or null
Compose Yml (string) or Compose Yml (null) (Compose Yml)

Raw docker-compose YAML content

RiskTier (integer) or null
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

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)
Fail If Model Type Unavailable (boolean) or Fail If Model Type Unavailable (null) (Fail If Model Type Unavailable)
Preferred Model Name (string) or Preferred Model Name (null) (Preferred Model Name)
Fail If Model Name Unavailable (boolean) or Fail If Model Name Unavailable (null) (Fail If Model Name Unavailable)
Preview Image (string) or Preview Image (null) (Preview Image)

Preview image URL

Kamiwaza Version (string) or Kamiwaza Version (null) (Kamiwaza Version)

Kamiwaza version constraint

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "version": "string",
  • "source_type": "kamiwaza",
  • "visibility": "private",
  • "compose_yml": "string",
  • "risk_tier": 0,
  • "validate_containers": true,
  • "env_defaults": {
    },
  • "description": "string",
  • "category": "string",
  • "tags": [
    ],
  • "author": "string",
  • "license": "string",
  • "homepage": "string",
  • "image": "string",
  • "capabilities": [
    ],
  • "required_env_vars": [
    ],
  • "preferred_model_type": "string",
  • "fail_if_model_type_unavailable": true,
  • "preferred_model_name": "string",
  • "fail_if_model_name_unavailable": true,
  • "preview_image": "string",
  • "kamiwaza_version": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "version": "string",
  • "source_type": "kamiwaza",
  • "visibility": "private",
  • "compose_yml": "string",
  • "risk_tier": 0,
  • "validate_containers": false,
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "env_defaults": {
    },
  • "description": "string",
  • "category": "string",
  • "tags": [
    ],
  • "author": "string",
  • "license": "string",
  • "homepage": "string",
  • "image": "string",
  • "capabilities": [
    ],
  • "required_env_vars": [
    ],
  • "preferred_model_type": "any",
  • "fail_if_model_type_unavailable": false,
  • "preferred_model_name": "string",
  • "fail_if_model_name_unavailable": false,
  • "preview_image": "string",
  • "kamiwaza_version": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "verified": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete App Template

Delete an app template.

path Parameters
template_id
required
string <uuid> (Template Id)

Responses

Response samples

Content type
application/json
null

List Kamiwaza App Garden

Responses

Response samples

Content type
application/json
[
  • { }
]

Get Garden Status

Get status of garden apps - database vs remote catalog.

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

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

Get Remote Template Status

Get status of remote templates - new available, updates available, etc.

Responses

Response samples

Content type
application/json
{ }

List Remote Apps

List available remote app templates.

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.

Responses

Response samples

Content type
application/json
null

Get Image Status

Check if images for a template have been pulled.

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.

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

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

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" } }

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" } }

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Responses

Response samples

Content type
application/json
[
  • { }
]

Update Tool Template

Update an existing tool template (local changes, no remote fetch).

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
TemplateVisibility (string) or null
Compose Yml (string) or Compose Yml (null) (Compose Yml)

Raw docker-compose YAML content

RiskTier (integer) or null
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

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)
Fail If Model Type Unavailable (boolean) or Fail If Model Type Unavailable (null) (Fail If Model Type Unavailable)
Preferred Model Name (string) or Preferred Model Name (null) (Preferred Model Name)
Fail If Model Name Unavailable (boolean) or Fail If Model Name Unavailable (null) (Fail If Model Name Unavailable)
Preview Image (string) or Preview Image (null) (Preview Image)

Preview image URL

Kamiwaza Version (string) or Kamiwaza Version (null) (Kamiwaza Version)

Kamiwaza version constraint

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "version": "string",
  • "source_type": "kamiwaza",
  • "visibility": "private",
  • "compose_yml": "string",
  • "risk_tier": 0,
  • "validate_containers": true,
  • "env_defaults": {
    },
  • "description": "string",
  • "category": "string",
  • "tags": [
    ],
  • "author": "string",
  • "license": "string",
  • "homepage": "string",
  • "image": "string",
  • "capabilities": [
    ],
  • "required_env_vars": [
    ],
  • "preferred_model_type": "string",
  • "fail_if_model_type_unavailable": true,
  • "preferred_model_name": "string",
  • "fail_if_model_name_unavailable": true,
  • "preview_image": "string",
  • "kamiwaza_version": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "version": "string",
  • "source_type": "kamiwaza",
  • "visibility": "private",
  • "compose_yml": "string",
  • "risk_tier": 0,
  • "validate_containers": false,
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "env_defaults": {
    },
  • "description": "string",
  • "category": "string",
  • "tags": [
    ],
  • "author": "string",
  • "license": "string",
  • "homepage": "string",
  • "image": "string",
  • "capabilities": [
    ],
  • "required_env_vars": [
    ],
  • "preferred_model_type": "any",
  • "fail_if_model_type_unavailable": false,
  • "preferred_model_name": "string",
  • "fail_if_model_name_unavailable": false,
  • "preview_image": "string",
  • "kamiwaza_version": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "verified": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update Tool Template

Update an existing tool template (local changes, no remote fetch).

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
TemplateVisibility (string) or null
Compose Yml (string) or Compose Yml (null) (Compose Yml)

Raw docker-compose YAML content

RiskTier (integer) or null
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

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)
Fail If Model Type Unavailable (boolean) or Fail If Model Type Unavailable (null) (Fail If Model Type Unavailable)
Preferred Model Name (string) or Preferred Model Name (null) (Preferred Model Name)
Fail If Model Name Unavailable (boolean) or Fail If Model Name Unavailable (null) (Fail If Model Name Unavailable)
Preview Image (string) or Preview Image (null) (Preview Image)

Preview image URL

Kamiwaza Version (string) or Kamiwaza Version (null) (Kamiwaza Version)

Kamiwaza version constraint

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "version": "string",
  • "source_type": "kamiwaza",
  • "visibility": "private",
  • "compose_yml": "string",
  • "risk_tier": 0,
  • "validate_containers": true,
  • "env_defaults": {
    },
  • "description": "string",
  • "category": "string",
  • "tags": [
    ],
  • "author": "string",
  • "license": "string",
  • "homepage": "string",
  • "image": "string",
  • "capabilities": [
    ],
  • "required_env_vars": [
    ],
  • "preferred_model_type": "string",
  • "fail_if_model_type_unavailable": true,
  • "preferred_model_name": "string",
  • "fail_if_model_name_unavailable": true,
  • "preview_image": "string",
  • "kamiwaza_version": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "version": "string",
  • "source_type": "kamiwaza",
  • "visibility": "private",
  • "compose_yml": "string",
  • "risk_tier": 0,
  • "validate_containers": false,
  • "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  • "env_defaults": {
    },
  • "description": "string",
  • "category": "string",
  • "tags": [
    ],
  • "author": "string",
  • "license": "string",
  • "homepage": "string",
  • "image": "string",
  • "capabilities": [
    ],
  • "required_env_vars": [
    ],
  • "preferred_model_type": "any",
  • "fail_if_model_type_unavailable": false,
  • "preferred_model_name": "string",
  • "fail_if_model_name_unavailable": false,
  • "preview_image": "string",
  • "kamiwaza_version": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "verified": false,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete Tool Template

Delete a tool template (only if no active deployments exist).

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).

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.

Responses

Response samples

Content type
application/json
{ }

Get Tool Garden Status

Get status of tool templates - database vs remote catalog.

Responses

Response samples

Content type
application/json
{ }

Get Tool Remote Status

Get status of remote tool templates - new available, updates available, etc.

Responses

Response samples

Content type
application/json
{ }

Get Tool Remote Status

Get status of remote tool templates - new available, updates available, etc.

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

Returns: Import results including counts and any errors

Raises: HTTPException: On validation errors or import failures

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

Returns: Import results including counts and any errors

Raises: HTTPException: On validation errors or import failures

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.

query Parameters
force_refresh
boolean (Force Refresh)
Default: false

Responses

Response samples

Content type
application/json
[
  • { }
]

List Remote Tools

List available remote tool templates.

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).

Responses

Response samples

Content type
application/json
null

Import Tool Garden Servers

Import tool templates from remote catalog (not from local file).

Responses

Response samples

Content type
application/json
null

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. 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. 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