Management API

Purpose

Management endpoints let an integration configure Kitemesh objects through the public API: secrets, tools, API resources, files, custom models, and group models.

Use them only with API tokens that need to change configuration. Keep these capabilities disabled for chat-only integrations.

Authentication and capabilities

All endpoints require:

Authorization: Bearer km_your_token_here

The token must belong to the team where the objects are managed. It must also have the matching capability:

Resource	Required capability
Secrets	manageSecrets
Tools	manageTools
API resources	manageResources
Files	uploadFiles for upload; resource access for read and delete
Custom models	manageCustomModels
Group models	manageGroups

Share scopes must also be allowed by the token scope policy. A share scope has this shape:

{
  "type": "team",
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Accepted type values are team, customModel, and groupModel.

List endpoints

List endpoints return objects visible to the token. Pagination fields depend on the resource family.

Endpoint	Useful query fields
GET /v1/secrets	scope, teamId, q, limit, cursor
GET /v1/tools	scopeType, scopeId, page, pageSize
GET /v1/api-resources	scopeType, scopeId, page, pageSize
GET /v1/files	scopeType, scopeId, resourceType, status, search, page, pageSize
GET /v1/custom-models	scope, teamId, search, category, tags, sort, credentialMode, limit, cursor
GET /v1/group-models	scope, teamId, search, category, tags, sort, mode, limit, cursor

Common limits:

• limit: 1 to 100 on secrets and model lists
• pageSize: 1 to 100 on tools, API resources, and files
• scope: mine, team, public, or all on model lists
• sort: updated, created, name, or author on model lists

Secrets

Secrets store sensitive values used by tools and BYOK custom models. Secret values can be written or rotated, but clients should not expect list and read responses to reveal the value.

Method and path	Purpose
POST /v1/secrets	create a secret
GET /v1/secrets	list visible secrets
PATCH /v1/secrets/:id	update metadata or rotate the value
DELETE /v1/secrets/:id	delete a secret

Create fields:

Field	Type	Required	Notes
name	string	yes	1 to 160 characters
description	string	no	up to 2000 characters
provider	string	no	up to 80 characters
scope	string	yes	user or team
teamId	string	no	UUID; required for a team-scoped secret
value	string	yes	secret value

Update accepts name, description, provider, and value.

curl -X POST "https://your-kitemesh.example.com/v1/secrets" \
  -H "Authorization: Bearer km_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer API key",
    "provider": "customer-api",
    "scope": "team",
    "teamId": "123e4567-e89b-12d3-a456-426614174000",
    "value": "secret_value_here"
  }'

Tools

Tools are HTTP actions. Use them for operations that create, update, or delete data, or for reads that need user approval controls.

Method and path	Purpose
POST /v1/tools	create a tool
GET /v1/tools	list visible tools
GET /v1/tools/:id	read one tool
PATCH /v1/tools/:id	update a tool
DELETE /v1/tools/:id	delete a tool

Create fields:

Field	Type	Required	Notes
name	string	yes	1 to 120 characters
description	string	yes	1 to 4000 characters
method	string	yes	POST, PATCH, PUT, or DELETE
needUserValidation	boolean	no	defaults to true when omitted
argsSchema	object	no	JSON schema-like object for arguments
urlTemplate	string	yes	target URL template
staticHeadersNonSecret	object	no	non-secret headers only
timeoutMs	integer	no	0 to 120000
authFields	array	no	entries with key and secretId
scopes	array	no	share scopes
tags	array<string>	no	tag labels
version	string	no	caller-defined version label

Update accepts the mutable tool fields. method, scopes, tags, and version are create-time fields for the public contract.

curl -X POST "https://your-kitemesh.example.com/v1/tools" \
  -H "Authorization: Bearer km_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Create support ticket",
    "description": "Creates a support ticket for the current customer.",
    "method": "POST",
    "needUserValidation": true,
    "urlTemplate": "https://api.example.com/tickets",
    "argsSchema": {
      "type": "object",
      "properties": {
        "priority": { "type": "string" },
        "summary": { "type": "string" }
      },
      "required": ["summary"]
    },
    "authFields": [
      {
        "key": "Authorization",
        "secretId": "123e4567-e89b-12d3-a456-426614174222"
      }
    ],
    "scopes": [
      {
        "type": "groupModel",
        "id": "123e4567-e89b-12d3-a456-426614174000"
      }
    ]
  }'

API resources

API resources expose read-only HTTP context. They are GET resources and are separate from action tools.

Method and path	Purpose
POST /v1/api-resources	create an API resource
GET /v1/api-resources	list visible API resources
GET /v1/api-resources/:id	read one API resource
PATCH /v1/api-resources/:id	update an API resource
DELETE /v1/api-resources/:id	delete an API resource

Create fields:

Field	Type	Required	Notes
name	string	yes	1 to 120 characters
description	string	yes	1 to 4000 characters
urlTemplate	string	yes	GET URL template
staticHeadersNonSecret	object	no	non-secret headers only
timeoutMs	integer	no	0 to 120000
cacheTtlSeconds	integer	no	0 or greater
scopes	array	no	share scopes

Update accepts name, description, urlTemplate, staticHeadersNonSecret, timeoutMs, and cacheTtlSeconds.

Files

Files are uploaded as multipart form data. The form must contain one file part and one metadata field containing JSON.

Method and path	Purpose
POST /v1/files	upload a file
GET /v1/files	list visible files
GET /v1/files/vectorization-status	read processing status for one or more files
GET /v1/files/:id	read one file resource
DELETE /v1/files/:id	delete one file resource

metadata fields:

Field	Type	Required	Notes
resourceType	string	yes	text, image, audio, or video
scope	string	no	user or conversation
conversationId	string	no	UUID for a conversation-scoped upload
scopes	array	no	share scopes
fileName	string	no	up to 255 characters

The default upload limit is 5 MB. The metadata field is limited to 64 KB by default.

curl -X POST "https://your-kitemesh.example.com/v1/files" \
  -H "Authorization: Bearer km_your_token_here" \
  -F "file=@./brief.pdf" \
  -F 'metadata={
    "resourceType": "text",
    "scope": "user",
    "fileName": "brief.pdf",
    "scopes": [
      {
        "type": "groupModel",
        "id": "123e4567-e89b-12d3-a456-426614174000"
      }
    ]
  }'

GET /v1/files/vectorization-status accepts ids as a comma-separated query parameter or repeated query parameter:

GET /v1/files/vectorization-status?ids=123e4567-e89b-12d3-a456-426614174000,123e4567-e89b-12d3-a456-426614174111

File statuses include pending, vectorizing, ready, failed, and deleting.

Custom models

Custom models wrap an LLM with reusable instructions, visibility, and credential settings.

Method and path	Purpose
POST /v1/custom-models	create a custom model
GET /v1/custom-models	list visible custom models
GET /v1/custom-models/:id	read one custom model
PATCH /v1/custom-models/:id	update a custom model
DELETE /v1/custom-models/:id	delete a custom model

Create fields:

Field	Type	Required	Notes
name	string	yes	1 to 200 characters
llmModelName	string	yes	model name
description	string	no	up to 2000 characters
category	string	no	up to 80 characters
tags	array<string>	no	each tag up to 64 characters
defaultSystemInstruction	string	no	up to 20000 characters
isPublic	boolean	no	public visibility flag
teamIds	array<string>	no	UUIDs of teams with access
credentialMode	string	no	app or byok
byokSecretId	string	no	UUID of a vault secret for BYOK

The same fields are accepted on update, with all fields optional.

Use the created model in chat with model: "custom:<uuid>".

Group models

Group models combine a brain target, optional agents, and a default mode.

Method and path	Purpose
POST /v1/group-models	create a group model
GET /v1/group-models	list visible group models
GET /v1/group-models/:id	read one group model
PATCH /v1/group-models/:id	update a group model
DELETE /v1/group-models/:id	delete a group model

Create fields:

Field	Type	Required	Notes
name	string	yes	1 to 200 characters
description	string	no	up to 2000 characters
category	string	no	up to 80 characters
tags	array<string>	no	each tag up to 64 characters
icon	string	no	supported icon name
defaultMode	string	yes	orch, synth, normal, or auto
brain	object	yes	model reference
agents	array	no	agent references
isPublic	boolean	no	public visibility flag
teamIds	array<string>	no	UUIDs of teams with access

Supported icon values are account_tree, forum, travel_explore, edit_note, monitoring, gavel, school, smart_toy, support_agent, campaign, analytics, and history_edu.

brain and agents[].ref use model references:

{
  "type": "llm",
  "llmModelName": "gpt-5-mini"
}

Agent entries can also include:

Field	Type	Notes
role	string	1 to 64 characters
instructionOverride	string	up to 20000 characters

GET /v1/group-models/:id accepts resolve=none, resolve=shallow, or resolve=deep. Resolution adds readable details for model references when the token can access them.

curl -X POST "https://your-kitemesh.example.com/v1/group-models" \
  -H "Authorization: Bearer km_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research group",
    "defaultMode": "auto",
    "brain": {
      "type": "llm",
      "llmModelName": "gpt-5-mini"
    },
    "agents": [
      {
        "ref": {
          "type": "custom",
          "customModelId": "123e4567-e89b-12d3-a456-426614174111"
        },
        "role": "researcher"
      }
    ],
    "teamIds": [
      "123e4567-e89b-12d3-a456-426614174000"
    ]
  }'

Use the created group in chat with model: "group:<uuid>".