Skip to content

Service and configuration endpoints ​

This page lists the service-level endpoints that are not bound to a single session, plus the configuration endpoints. Session endpoints are in Session endpoints, and file endpoints are in File endpoints. Shared conventions such as authentication, the response envelope, error codes, and pagination are in Server API.

A :{action} suffix in a path is the action convention: POST to path:action on a single resource or a resource collection to run a non-CRUD operation (such as :fork and :archive on a session, or :refresh on the provider collection).

Server and metadata ​

These endpoints report information about the server instance itself and provide liveness and shutdown entry points.

Method and pathDescription
GET /api/v1/healthzLiveness probe; auth-exempt
GET /api/v1/metaServer version, capability map, server_id, experimental flags
POST /api/v1/shutdownGraceful shutdown (replies 200 first); mounted only on a loopback bind or with --allow-remote-shutdown

GET /api/v1/healthz ​

Liveness probe for scripts and process supervisors. It is the only /api endpoint that does not require the bearer token (see Authentication), and it answers without touching config or the engine.

On success, data is { "ok": true }.

GET /api/v1/meta ​

Returns this instance's identity and capability map. Most fields are frozen at boot. experimental_flags and features are resolved on every request, so a flag flip or a failed feature shows up in the next response.

FieldTypeDescription
server_versionstringServer version
capabilitiesobjectCapability map: websocket, file_upload, fs_query, mcp, tasks, all always true
server_idstringUnique id of this server instance
started_atstringBoot time, ISO 8601
open_in_appsarrayHost apps usable as open-in targets: finder / cursor / vscode / iterm / terminal. Currently always empty
dangerous_bypass_authbooleanWhether the server was started with --dangerous-bypass-auth (when true, clients may skip the token prompt)
backendstringEngine backend: v1 / v2. Always v2 for this server
web_titlestringCustom browser tab title from --web-title; omitted when unset
experimental_flagsobjectExperimental flag id → enabled, resolved at request time
featuresarrayEngine features, each { name, state, meta }. state is Pending / Activating / Active / Unloading / Failed

POST /api/v1/shutdown ​

Asks the server to shut down gracefully. The server sends the response first and shuts down immediately after, so the caller can trust the response it received.

The route is mounted only when the server is bound to a loopback address or was started with --allow-remote-shutdown. Otherwise the route is not registered and requests get a 404.

On success, data is { "ok": true }.

Login and usage ​

These endpoints drive the managed Kimi OAuth login lifecycle and read account-level information. The managed provider is named managed:kimi-code, and the optional provider parameter on every endpoint below defaults to it.

Method and pathDescription
GET /api/v1/authAuth status snapshot
POST /api/v1/oauth/loginStart the OAuth device-code login flow
GET /api/v1/oauth/loginPoll the login flow state
DELETE /api/v1/oauth/loginCancel a pending login flow
POST /api/v1/oauth/logoutLog out the managed provider
GET /api/v1/oauth/usagePlan quota and booster wallet
GET /api/v1/oauth/userinfoAccount profile
GET /api/v1/oauth/regionResolve the client region (mainland-cn / global)

GET /api/v1/auth ​

Returns an auth status snapshot: whether the default model resolves to a usable provider configuration, and the managed provider's login state.

models_ready is true when the global default_model alias exists in the model table and resolves to a configured provider. Providerless flat models that carry their own base_url and models injected through KIMI_MODEL_* environment variables both count. The server does not verify credentials, so later conversation requests can still fail with 40111 / 40112.

FieldTypeDescription
models_readybooleanWhether the default model resolves to a configured provider; see the rule above
providers_countintegerNumber of configured providers
managed_providerobject | nullLogin state of the managed provider
managed_provider.namestringManaged provider name
managed_provider.statusstringauthenticated / expired / revoked / unauthenticated

This endpoint does not return the global default model alias. Read it from default_model in GET /api/v1/config instead.

POST /api/v1/oauth/login ​

Starts an OAuth device-code login flow for the managed provider. Starting a new flow aborts any pending flow for the same provider. When the account is already logged in, no user interaction is needed and the response reports authenticated directly.

ParameterInTypeDescription
providerbodystringManaged provider name. Default managed:kimi-code
regionbodystringmainland-cn / global. Overrides the region resolved by GET /api/v1/oauth/region for this flow only

On success, data.status is pending or authenticated. When the account is already logged in, data has only flow_id, provider, and status: "authenticated". For a pending flow, data has these fields:

FieldTypeDescription
flow_idstringFlow id
providerstringManaged provider name
statusstringpending
verification_uristringVerification page URL; open it and enter user_code
verification_uri_completestringVerification page URL that can be opened directly, without entering user_code
user_codestringUser code to enter on the verification_uri page
expires_inintegerFlow deadline in seconds. The same deadline as expires_at
intervalintegerPolling interval in seconds
expires_atstringFlow expiry time

With a pending flow, open verification_uri_complete (or open verification_uri and enter user_code), then poll GET /api/v1/oauth/login every interval seconds until the flow resolves or expires_at passes.

GET /api/v1/oauth/login ​

Polls the login flow state for a provider.

ParameterInTypeDescription
providerquerystringManaged provider name. Default managed:kimi-code

When no flow has been started, data is null. Otherwise data is a flow snapshot with every field of the pending shape of POST /api/v1/oauth/login. These fields differ in value or are added:

FieldTypeDescription
statusstringpending / authenticated / denied / expired / cancelled
resolved_atstringPresent once the flow leaves pending; records when the flow reached its terminal state
error_messagestringDescribes a failed flow; may be omitted

DELETE /api/v1/oauth/login ​

Cancels the pending login flow for a provider. When no flow is pending, the call does nothing and returns the last known state.

ParameterInTypeDescription
providerquerystringManaged provider name. Default managed:kimi-code

On success, data is { cancelled, status }. cancelled is true only when a pending flow was actually aborted. status is the flow state after the call.

POST /api/v1/oauth/logout ​

Logs out the managed provider: discards the stored OAuth credential, aborts any pending login flow, and removes the managed provider from the configuration. OAuth-managed providers cannot be edited or deleted manually (see PUT / DELETE /api/v1/providers/{provider_id}), so the only way to remove one is to log out first.

When you log out the default Kimi provider (managed:kimi-code), the server also tears down this machine's Remote Control and clears cached Remote Control cloud sessions. Logging out any other provider does not affect Remote Control. The teardown order depends on who hosts the tunnel:

  • No tunnel is running, or another process on this machine hosts it: the server first takes this machine's device offline and holds the machine lock, so no process on this machine can start Remote Control again before the credential is discarded. If the cleanup fails, the logout is aborted.
  • This server hosts the tunnel: the server discards the credential first and tears down the tunnel right after the response is sent, so a logout sent through the Remote Control link still receives its response.
ParameterInTypeDescription
providerbodystringManaged provider name. Default managed:kimi-code

On success, data is { logged_out: true, provider }.

  • 50001: logging out the default Kimi provider failed, either in the Remote Control cleanup or in the logout itself

GET /api/v1/oauth/usage ​

Reads the plan quota and booster wallet of the managed account, fetched live from the account service. When the account service fails, the envelope still succeeds and the error comes back inside data.

ParameterInTypeDescription
providerquerystringManaged provider name. Default managed:kimi-code

On success, data.kind is ok or error:

FieldTypeDescription
quota.usagesobjectok only: usage per time window, keyed by limit5h, limit7d, monthTotal, monthCode; clients render whichever keys are present. Each entry is { usedRatio, resetAt? }: usedRatio is the used fraction from 0 to 1 (a float), and resetAt is the reset time in RFC3339 format
quota.extraUsageobject | nullok only: the pay-as-you-go wallet, with fields balanceCents, totalCents, monthlyChargeLimitEnabled, monthlyChargeLimitCents, monthlyUsedCents, currency
messagestringerror only: error message
statusintegererror only: HTTP status code returned by the account service; omitted when there is none

GET /api/v1/oauth/userinfo ​

Reads the managed account's profile. Account service failures are handled the same way as in GET /api/v1/oauth/usage: the envelope still succeeds and the error comes back inside data.

ParameterInTypeDescription
providerquerystringManaged provider name. Default managed:kimi-code

On success, data.kind is ok or error:

FieldTypeDescription
userInfoobjectok only: account profile. Always contains userId, nickname, status, region, userLevel, userLevelName, domain, domainName; may add globalId, bio, avatar, username, email, phone ({ countryCode, number }), createdTime, and lastLoginTime
messagestringerror only: error message
statusintegererror only: HTTP status code returned by the account service; omitted when there is none

GET /api/v1/oauth/region ​

Resolves which Kimi region the client belongs to. The result is derived locally, without network probes. The server takes the first input that decides the region, in this order: an OAuth host pinned by environment variable or config, the configured OAuth key, and the install-channel marker in <home>/region.

When the client is logged out and none of those inputs decides the region, the server infers it from the device time zone and locale. When the inference gives a definite result, the server caches it in <home>/region.json and uses the cache from then on; the cache is cleared after the client logs in. Raw time zone and locale values are not uploaded.

When signals are missing or conflicting, the current process falls back to mainland-cn without persisting that result, and the next start decides again. Set KIMI_CODE_REGION_MARKER=off to disable both the install-channel marker and local inference. Local inference is also skipped when KIMI_CODE_BASE_URL is set.

On success, data is { region }, where region is mainland-cn / global.

Remote Control ​

These endpoints manage the machine-wide Remote Control tunnel (see the Remote Control guide) and the account's device registry. Tunnel state is per machine. The device registry is per account and stored in the cloud, so device endpoints require a Kimi login; the server holds the login session and proxies requests to the relay, so OAuth credentials never reach the caller.

Method and pathDescription
GET /api/v1/remote-controlRead the tunnel status
POST /api/v1/remote-controlStart or stop the tunnel
GET /api/v1/remote-control/devicesList the account's devices
PATCH /api/v1/remote-control/devices/{id}Rename a device
POST /api/v1/remote-control/devices/{id}/deactivateTake a device offline
DELETE /api/v1/remote-control/devices/{id}Remove a device from the registry

GET /api/v1/remote-control ​

Returns the current tunnel status. When the tunnel is off but another live process on this machine holds the single-instance lock, data.conflict carries the lock holder's information. While the tunnel is off, every read re-checks the lock; once the holder process exits, conflict and any stored error are cleared together.

On success, data is the tunnel status object:

FieldTypeDescription
enabledbooleanRemote Control switch
statestringoff / starting / on / stopping
urlstringTunnel URL; may be omitted
device_idstringThis machine's device identifier; may be omitted
device_namestringThis machine's device name; may be omitted
errorstringError message; may be omitted
conflictobjectLock holder information, present only in the conflict case above: { pid, local_origin, device_id, url, started_at }

POST /api/v1/remote-control ​

Starts or stops the tunnel.

ParameterInTypeDescription
enabledbodybooleantrue to start the tunnel, false to stop it

On success, data is the tunnel status object, the same as GET /api/v1/remote-control.

  • 40001 (VALIDATION_FAILED): on start, the server is not bound to a loopback address, or it was started with --dangerous-bypass-auth
  • 40928 (REMOTE_CONTROL_ALREADY_RUNNING): on start, another live process on this machine holds the single-instance lock. details carries the lock holder information, in the same shape as conflict
  • 50001 (INTERNAL_ERROR): starting or stopping the tunnel failed

GET /api/v1/remote-control/devices ​

Lists the account's Remote Control devices from the cloud registry.

On success, data is { devices, max_devices? }, where max_devices is the device limit. Each item in devices has these fields:

FieldTypeDescription
device_idstringDevice identifier
aliasstringDisplay name
statusstringonline / offline
platformstringDevice platform
client_versionstringClient version
local_base_urlstringDevice's local server URL
created_atstringCreation time
updated_atstringUpdate time
last_remote_access_atstringTime of the most recent remote access
  • 50001 (INTERNAL_ERROR): the request to the cloud registry failed

PATCH /api/v1/remote-control/devices/{id} ​

Renames a device.

ParameterInTypeDescription
idpathstringDevice identifier
aliasbodystringNew display name, 1–50 characters after trimming leading and trailing whitespace

On success, data is { ok: true }.

  • 40001 (VALIDATION_FAILED): the name is blank or too long. The server returns this before contacting the cloud
  • 50001 (INTERNAL_ERROR): the request to the cloud registry failed

POST /api/v1/remote-control/devices/{id}/deactivate ​

Marks a device offline in the cloud registry. Offline devices stay in the list and do not consume the plan's device quota; a device comes back online the next time it turns on Remote Control.

When the target device is this machine, the server first stops the local tunnel (an in-flight start is cancelled), then holds the machine lock while deactivating, so a concurrent start cannot re-register the device after the success response.

ParameterInTypeDescription
idpathstringDevice identifier

On success, data is { ok: true }.

  • 50001 (INTERNAL_ERROR): the request to the cloud registry failed. Also returned instead of success when the target device is this machine and the lock holder does not stop within the time limit

DELETE /api/v1/remote-control/devices/{id} ​

Removes a device from the cloud registry: the device disappears from the list, and a tunnel that is still connected is disconnected. Unlike deactivating, deleting does not keep the device in the list.

When the target device is this machine, the server first stops the local tunnel, then holds the machine lock while deleting, so the device cannot re-register after the success response.

ParameterInTypeDescription
idpathstringDevice identifier

On success, data is { ok: true }.

  • 50001 (INTERNAL_ERROR): the request to the cloud registry failed. Also returned when the target device is this machine and the lock holder does not stop within the time limit

Configuration ​

These endpoints read and write the global configuration (config.toml) and read client configurations delivered remotely by the Kimi Code service.

Method and pathDescription
GET /api/v1/configRead the global config (secret fields redacted)
POST /api/v1/configMerge-patch the config and broadcast event.config.changed
POST /api/v1/client_configsRead a named client configuration controlled remotely by the Kimi Code service

GET /api/v1/config ​

Returns the resolved global configuration: the effective result of config.toml plus overlays. Secrets are redacted: each provider reports only has_api_key, never the stored key.

On success, data is the config object. Its fields map one-to-one to the top-level domains in Top-level fields:

FieldTypeDescription
providersobjectMap of provider id → { type, base_url?, default_model?, api_key_env?, has_api_key }
default_providerstringGlobal default provider id
default_modelstringGlobal default model alias
modelsobjectMap of model alias → model record
thinkingobjectDefault parameters for Thinking mode
plan_modebooleanPlan mode switch
yolobooleanDerived: true when default_permission_mode is yolo
default_permission_modestringDefault permission mode for new sessions
default_plan_modebooleanWhether new sessions start in Plan mode
permissionobjectInitial permission rules
hooksarrayLifecycle hooks
servicesobjectBuilt-in external service configuration
merge_all_available_skillsbooleanWhether to merge Agent Skills from all available directories
extra_skill_dirsarrayExtra skill search directories
loop_controlobjectAgent loop control parameters
backgroundobjectBackground task runtime parameters
subagentobjectSubagent configuration
secondary_modelobjectSecondary model pool for subagents
experimentalobjectExperimental flag id → enabled
telemetrybooleanWhether anonymous telemetry is enabled
auto_session_titlebooleanWhether clients may automatically generate session titles
disable_feedback_surveybooleanWhether the session rating prompt is turned off
rawobjectRaw parsed config.toml content, unmodeled fields included

POST /api/v1/config ​

Merge-patches the global configuration. Each top-level domain in the request body is deep-merged into the matching domain, and domains absent from the body stay unchanged.

The request body is a partial config object: it may contain any top-level domain of the GET /api/v1/config response except raw, all optional, with the same types and meanings as the response table. Two domains have extra write rules:

  • yolo: true is shorthand for default_permission_mode: "yolo"; false is ignored.
  • default_permission_mode: one of manual / yolo / auto.

On success, data is the full updated config, in the same shape as GET /api/v1/config.

Every config change broadcasts the global event event.config.changed (see Global events). This covers a successful update through this endpoint, an edit of config.toml outside the process, and server-side writes such as an OAuth login refresh. Changes within a short window are merged into one event: changedFields carries the affected domain names (camelCase config domains, for example defaultModel), and config carries the full current config projection (same shape as the GET /api/v1/config response).

  • 40001: the patch was rejected (invalid value or persistence failure); the response carries the underlying error message

POST /api/v1/client_configs ​

Reads a named client configuration that the Kimi Code service controls remotely, including which model or thinking-effort switches ask the user to confirm, and the client upgrade policy. The server reads it from the Kimi Code service of the account's region (or from KIMI_CODE_BASE_URL when that is set) and normalizes the result to the shape that name expects.

ParameterInTypeDescription
namebodystringRequired. model_switch_confirm / effort_switch_confirm / client_upgrade_policy

On success, data is { name, config }. When the name is outside that list or the read fails, config is null and the client falls back to its built-in behavior.

A value that was read never becomes null: fields that are missing or malformed take their off defaults. For example, a malformed model_switch_confirm comes back as { enable: false, rules: [] }.

Models and providers ​

These endpoints manage the two halves of model configuration in config.toml: the providers table and the model alias table. A server-proxied models.dev directory is also available for one-shot provider imports.

A model alias id is the alias key in the configuration. Aliases created through the provider-management endpoints take the form provider_id/model (for example my-provider/kimi-for-coding), while a bare key in the model alias table (such as turbo) is used as-is. Anywhere the API takes a model_id, including the global default_model, it means this alias id.

An unsupported action on a :{action} route returns 40001.

Method and pathDescription
GET /api/v1/modelsList configured model aliases
POST /api/v1/models/{model_id}:set_defaultSet the global default model
GET /api/v1/providersList providers
POST /api/v1/providersCreate a provider (201)
GET /api/v1/providers/{provider_id}Read a provider (includes the stored key)
PUT /api/v1/providers/{provider_id}Replace a provider's configuration
DELETE /api/v1/providers/{provider_id}Delete a provider (204)
POST /api/v1/providers/{provider_id}:refreshRefresh this provider's model metadata
POST /api/v1/providers:{action}Collection actions: refresh / refresh_oauth / import_catalog (201) / import_registry (201)
GET /api/v1/catalog/providersBrowse the models.dev directory (server-proxied)
GET /api/v1/catalog/providers/{catalog_id}Read one directory entry

GET /api/v1/models ​

Lists the configured model aliases across all providers.

On success, data.items is an array of models, each with these fields:

FieldTypeDescription
providerstringOwning provider id
modelstringAlias id: provider_id/model for provider-managed aliases, otherwise the bare key
display_namestringDisplay name; may be omitted
max_context_sizeintegerContext window in tokens
capabilitiesarrayCapability flags; may be omitted
support_effortsarraySupported Thinking mode effort levels; may be omitted
default_effortstringDefault effort level; may be omitted
upgradeobjectMay be present on custom registry models, to guide users toward a replacement model
upgrade.modelstringReplacement model
upgrade.migration_markdownstringMigration notes, with placeholders already replaced by model ids
upgrade.retirement_atstringRetirement time; may be omitted

POST /api/v1/models/{model_id}:set_default ​

Sets the global default_model to an existing alias. model_id is the exact alias key from the configuration. For a bare key the call is POST /api/v1/models/turbo:set_default; URL-encode the id when it contains /, as in POST /api/v1/models/my-provider%2Fkimi-for-coding:set_default.

ParameterInTypeDescription
model_idpathstringRequired. The exact model alias key from the configuration; URL-encode it when it contains /

On success, data is { default_model, model }: default_model is the alias now in effect, and model is its catalog item (same shape as a GET /api/v1/models item).

  • 40001: malformed or unsupported action suffix in the path
  • 40413: no model alias with that id

GET /api/v1/providers ​

Lists every configured provider with its credential and model-discovery state, without revealing any key. This item shape is also the "provider item" referenced by the other provider endpoints.

On success, data.items is an array of provider items:

FieldTypeDescription
idstringProvider id
typestringWire protocol, returned as the value in the configuration (for values written through these endpoints, see type in POST /api/v1/providers); openai when the configuration does not set it
base_urlstringAPI base URL; omitted when unset
default_modelstringThe provider's default model alias. When the provider does not set one but the global default_model belongs to this provider, the global value is used; otherwise omitted
api_key_envstringName of the environment variable the API key is read from; omitted when unset
has_api_keybooleanWhether a usable API key exists: a non-empty api_key is configured, the environment variable named by api_key_env has a value, or the provider's env supplies a key
statusstringerror when the credential configuration conflicts (api_key and api_key_env both present, or either one present together with OAuth); otherwise connected when an API key or a cached OAuth token exists, and unconfigured when neither does
modelsarrayThe provider's model alias ids

POST /api/v1/providers ​

Creates a provider and its model aliases in one save. On success, the reply is HTTP 201 with the standard envelope. When no global default_model is configured at all (a fresh install), the server seeds it with the new provider's default_model (or first model); an existing default is never modified.

Credentials are one of two forms: api_key stores the key directly, while api_key_env records the name of the environment variable to read the key from. A request that passes non-empty values for both is rejected.

ParameterInTypeDescription
idbodystringRequired. Provider id. Only letters, digits, -, _, and spaces; must start with a letter or digit
typebodystringRequired. Wire protocol: kimi / openai / openai_responses / anthropic / bedrock / google-genai / vertexai
api_keybodystringAPI key, stored in config.toml
api_key_envbodystringName of the environment variable to read the API key from. The server stores only the variable name, not the key
base_urlbodystringAPI base URL; must not contain an environment variable placeholder (${...})
default_modelbodystringThe provider's default model; must be one of models[].model
modelsbodyarrayRequired. At least one entry, no duplicate model values; entry shape below

Each models[] entry declares one alias whose id is id/model:

FieldTypeDescription
modelstringRequired. Upstream model name
max_context_sizeintegerRequired. Context window in tokens, ≥ 1
display_namestringDisplay name
capabilitiesarrayCapability flags such as thinking or image_in
protocolstringWire-protocol override: anthropic, openai, or openai_responses; inferred from the model ID when omitted
max_output_sizeintegerMax output tokens, ≥ 1
support_effortsarraySupported Thinking mode effort levels
adaptive_thinkingbooleanAdaptive thinking switch

On success, data is the created provider item (same shape as a GET /api/v1/providers item).

  • 40001: body validation failed, or both api_key and api_key_env were passed with non-empty values
  • 40921: a provider with this id already exists

GET /api/v1/providers/{provider_id} ​

Reads one provider. Unlike the list endpoint, the response includes the stored api_key when one is set, so a local edit form can prefill it. Keep this in mind when exposing the server port.

ParameterInTypeDescription
provider_idpathstringRequired. Provider id

On success, data is the provider item, plus api_key when a key is stored.

  • 40412: provider not found

PUT /api/v1/providers/{provider_id} ​

Replaces a provider in one save. type, base_url, and the model list are rewritten, and the provider's aliases are rebuilt from models: aliases no longer listed disappear from config.toml, while other providers' aliases are untouched. Apart from the migration caused by a new_id rename, this endpoint does not modify the global default pointers.

api_key and api_key_env each accept three forms: omitted keeps the stored value, "" clears it, and any other value replaces it. The two are mutually exclusive: a non-empty value for one clears the other, and a request with non-empty values for both is rejected.

ParameterInTypeDescription
provider_idpathstringRequired. Current provider id
new_idbodystringRename the provider. The providers key, model aliases, default_provider, a default_model pointing at an old alias, and the subagent secondary model pool all migrate. Same id rules as POST /api/v1/providers
typebodystringRequired. Wire protocol: kimi / openai / openai_responses / anthropic / bedrock / google-genai / vertexai
api_keybodystringAPI key; three forms, see above
api_key_envbodystringName of the environment variable to read the API key from; three forms, see above
base_urlbodystringAPI base URL; must not contain an environment variable placeholder (${...})
default_modelbodystringThe provider's default model; must be one of models[].model
modelsbodyarrayRequired. At least one entry, no duplicate model values; same entry shape as POST /api/v1/providers

On success, data is { provider }, where provider is the saved provider item.

  • 40001: body validation failed, both api_key and api_key_env were passed with non-empty values, or a renamed alias id would collide with another provider's alias
  • 40003: the provider is OAuth-managed; log out with POST /api/v1/oauth/logout instead
  • 40412: provider not found
  • 40921: new_id is already taken

DELETE /api/v1/providers/{provider_id} ​

Deletes a provider and all of its model aliases, and cascades the cleanup to the subagent secondary model pool. The global default_provider / default_model pointers stay unchanged, even when they point at the deleted provider. These two values are the user's settings, and this endpoint does not reclaim them.

ParameterInTypeDescription
provider_idpathstringRequired. Provider id

On success, the server returns HTTP 204 with no body; the status code itself reports the successful delete (see Response envelope).

  • 40003: the provider is OAuth-managed; log out with POST /api/v1/oauth/logout instead
  • 40412: provider not found

POST /api/v1/providers/{provider_id}:refresh ​

Re-discovers one provider's model metadata from its upstream source and rewrites the provider's aliases. A provider with a static model source makes no network request and is reported as unchanged directly.

This endpoint and the collection-level :refresh and :refresh_oauth follow the same broadcast rule. When the refresh report's changed is non-empty (at least one provider's aliases or managed model metadata changed), the server broadcasts the global event event.model_catalog.changed (see Global events), with the same content as the refresh report.

ParameterInTypeDescription
provider_idpathstringRequired. Provider id

On success, data is a refresh report:

FieldTypeDescription
changedarrayProviders that changed, each { provider_id, provider_name, added, removed }; added / removed are the numbers of aliases added / removed
unchangedarrayIds of providers with no diff
failedarrayProviders whose refresh failed, each { provider, reason }
retired_defaultobjectOptional. Present when the refresh finds that the registry dropped the current default model and that model had declared an upgrade replacement: { from, to, from_display_name }

When retired_default is present, the default model has been redirected to to, and open sessions still bound to from have also been switched to to. from_display_name is the dropped model's display name, for use in notices. The same field also appears in the event.model_catalog.changed event.

  • 40001: malformed or unsupported action suffix in the path
  • 40412: provider not found

POST /api/v1/providers:refresh ​

Refreshes the model metadata of every provider. The request body is optional, and its content is ignored.

On success, data is a refresh report with the same structure as POST /api/v1/providers/{provider_id}:refresh, and it can also carry retired_default.

POST /api/v1/providers:refresh_oauth ​

Refreshes only the model list of the managed provider managed:kimi-code. When that provider does not exist or is not OAuth-managed, nothing is refreshed and an empty report is returned. The request body is optional, and its content is ignored.

On success, data is a refresh report with only changed / unchanged / failed, without retired_default.

POST /api/v1/providers:import_catalog ​

Imports one models.dev directory entry as a configured provider. On success, the reply is HTTP 201 with the standard envelope. The wire protocol and endpoint come from the catalog resolution, and every model in the entry is written as an alias.

Importing an id that already exists is a refresh: the provider entry and its aliases are rewritten from the catalog, and an omitted api_key keeps the stored key. This endpoint does not modify existing global default pointers. Only when no default model is configured at all is default_model seeded with the first imported model.

ParameterInTypeDescription
catalog_idbodystringRequired. Directory entry id from GET /api/v1/catalog/providers
idbodystringLocal provider id, overriding the catalog id. Same id rules as POST /api/v1/providers
api_keybodystringAPI key for the imported provider
base_urlbodystringOverrides the catalog-resolved endpoint. Required when the entry's needs_base_url is true

On success, data is { provider, models_imported }: provider is the provider item, and models_imported is the number of aliases written.

  • 40001: catalog_id is missing, or another body validation failed
  • 40003: the target provider already exists and is OAuth-managed
  • 40004: the entry cannot be imported (it is rejected, requires a base_url, has no importable models, or its id cannot be used as a provider id)
  • 40417: no directory entry with that catalog_id
  • 50004: the models.dev directory is unavailable

POST /api/v1/providers:import_registry ​

Imports a models.dev-shaped private registry (an api.json URL plus an optional Bearer key) as configured providers. On success, the reply is HTTP 201 with the standard envelope. Every provider the registry lists is written with a source record, so scheduled refreshes can rediscover it.

Re-importing the same URL removes providers that have disappeared upstream. The URL is the registry's stable identity, so rotating the key is safe. Global default pointers follow the same rules as :import_catalog.

ParameterInTypeDescription
urlbodystringRequired. URL of the registry's api.json
api_keybodystringBearer key for the registry. When omitted, the key from the previous import of the same URL is reused

On success, data has these fields:

FieldTypeDescription
providersarrayImported provider items
models_importedintegerTotal number of aliases written
credential_envobjectMap of provider id → environment variable name. When the registry declares API key environment variables for a provider, this is the first non-empty variable name among them
  • 40001: url is missing, or another body validation failed
  • 40003: a listed provider already exists and is OAuth-managed
  • 40005: the registry cannot be fetched or parsed, or lists no importable providers

GET /api/v1/catalog/providers ​

Browses the models.dev directory. The server proxies the request with a 10-minute in-memory cache and falls back to a built-in snapshot. Entries keep the upstream directory order.

Entries the server cannot import carry rejected: true and a machine-readable reject_reason. Entries with needs_base_url: true require a base URL at import time.

On success, data.items is an array of directory entries:

FieldTypeDescription
idstringDirectory entry id
namestringEntry name
wire_typestring | nullResolved protocol, same enum as a provider type
base_urlstring | nullResolved endpoint. null for entries whose needs_base_url is true or that are rejected
guessedbooleanWhether the resolution is heuristic
needs_base_urlbooleanWhether a base URL is required at import time
rejectedbooleanWhether the server cannot import this entry
reject_reasonstring | nullMachine-readable rejection reason
env_keystring | nullThe upstream's conventional API key environment variable
modelsarrayEach item is { id, name?, max_context_size, capabilities?, reasoning }
  • 50004: the directory is unavailable (both the live fetch and the built-in snapshot failed)

GET /api/v1/catalog/providers/{catalog_id} ​

Reads one models.dev directory entry by catalog id.

ParameterInTypeDescription
catalog_idpathstringRequired. Directory entry id

On success, data is the directory entry, in the same shape as a GET /api/v1/catalog/providers item.

  • 40417: no directory entry with that catalog_id
  • 50004: the directory is unavailable

Skills, tools, and MCP ​

These endpoints show the skill catalog a workspace sees and the tool list of the effective agent. For MCP server registry CRUD, connection probes, and OAuth, see MCP management. For the per-session skill catalog and skill activation (the REST equivalent of the /<skill> slash command), see Session skills.

Method and pathDescription
GET /api/v1/workspaces/{workspace_id}/skillsSession-less skill catalog for a workspace
GET /api/v1/toolsList tools of the effective agent
/api/v1/mcp/*MCP server registry CRUD, connection probes, and OAuth; see MCP management

GET /api/v1/workspaces/{workspace_id}/skills ​

Lists the skill catalog that a session in this workspace would see, without creating or resuming a session. The catalog is computed for the workspace's primary directory and extra source folders, and merges the same sources as a session: built-in, plugin, extra, user, and project.

ParameterInTypeDescription
workspace_idpathstringRequired. Registered workspace id

On success, data is { skills }. Each item is a skill descriptor, in the same shape returned by Session skills:

FieldTypeDescription
namestringSkill name. Same-name skills can be returned as multiple variants with distinct path values
descriptionstringSkill description
pathstringPath of the skill
sourcestringproject / user / extra / builtin
workspace_dirstringRoot directory of a project skill; omitted for other sources
typestringOptional. Skill category; only user-activatable types can be activated
disable_model_invocationbooleanOptional. When true, the skill is hidden from the model
scopesstring[]Optional. Clients the skill declares it applies to: tui / web
  • 40410: workspace not found

GET /api/v1/tools ​

Lists the tools of the effective agent. The effective agent is the main agent of the selected session, and the session is picked in one of two ways:

  • session_id passed: the server resumes that session on demand, loading a cold session into this server process as well. When the session does not exist, the list is empty.
  • session_id omitted: the most recently created session is used, but it is not resumed. When that session is not live in this server process, the list is empty; there is no fallback to an older live session.
ParameterInTypeDescription
session_idquerystringSession whose main agent to inspect. Default the most recently created session

On success, data is { tools }, each item with these fields:

FieldTypeDescription
namestringTool name
descriptionstringTool description
input_schemanullCurrently always null
sourcestringbuiltin / skill / mcp
mcp_server_idstringPresent only on MCP tools, parsed from the mcp__<server>__<tool> tool name
activebooleanOptional. The tool policy's verdict

Capabilities and plugins ​

These endpoints query the readiness of built-in capabilities and install them, and manage the full plugin lifecycle from marketplace browsing and installation to removal.

Capabilities are built-in features made of detection steps and a background install, with graded readiness (see state in Capability status object). The current build registers kimi-cu (Kimi Computer Use) and kimi-webbridge (Kimi Browser Extension). Plugins are installed bundles of skills, MCP servers, hooks, and commands.

Method and pathDescription
GET /api/v1/capabilitiesList built-in capabilities with their readiness status
GET /api/v1/capabilities/{capability_id}Read one capability's status
POST /api/v1/capabilities/{capability_id}:installStart a capability install (runs in the background; poll GET for progress)
GET /api/v1/pluginsList installed plugins
GET /api/v1/plugins/{plugin_id}Read an installed plugin and its declared capabilities
POST /api/v1/pluginsInstall a custom plugin, or a marketplace entry at an expected version
POST /api/v1/plugins/previewInspect a marketplace entry's capabilities read-only, without installing it
GET /api/v1/plugins/marketplacePlugin marketplace catalog merged with live install state
POST /api/v1/plugins/{plugin_id}:enableEnable a plugin
POST /api/v1/plugins/{plugin_id}:disableDisable a plugin
POST /api/v1/plugins/{plugin_id}:removeRemove a plugin

Capability status object ​

Every capability endpoint returns this structure.

FieldTypeDescription
idstringCapability id
pluginIdstringOptional. Plugin id
displayNamestringDisplay name
descriptionstringDescription
supportedbooleanWhether the current platform is supported
statestringready (every required detection step is ok) / partial (some steps are ok) / not_installed / unsupported (not available on the current platform / architecture)
versionstringOptional. Version
stepsarrayDetection steps, each { id, state, detail?, optional? }, where state is ok / missing / failed
install.runningbooleanWhether an install is running
install.stepstringOptional. Current install step
install.percentnumberOptional. Install progress, from 0 to 100
install.errorstringOptional. Install error
install.notestringOptional. Install note
install.confirmationRequiredstringOptional. When stop-processes, the install stopped because related processes are still running; after the user confirms, install again with stopRunningProcesses: true

GET /api/v1/capabilities ​

Lists every registered capability with its readiness status.

On success, data is { capabilities }, where each item is a capability status object.

GET /api/v1/capabilities/{capability_id} ​

Reads one capability's readiness status. After starting an install, clients poll this endpoint for progress.

ParameterInTypeDescription
capability_idpathstringRequired. Capability id

On success, data is a capability status object.

  • 40418: no capability with that id

POST /api/v1/capabilities/{capability_id}:install ​

Starts installing a capability in the background and immediately returns the current status (with install.running set to true). Clients poll GET /api/v1/capabilities/{capability_id} for progress.

The server dispatches through the route POST /api/v1/capabilities/{tail}, and install is the only action. A bare id or an unknown action returns 40001.

ParameterInTypeDescription
capability_idpathstringRequired. Capability id
stopRunningProcessesbodybooleanOptional. When true, the install may stop related processes that are still running. The request body may be omitted

On success, data is a capability status object.

Currently only kimi-cu on Windows checks for running processes. When related processes exist and stopRunningProcesses: true was not passed, the background install ends with install.confirmationRequired set to stop-processes.

  • 40001: missing or unknown action suffix
  • 40418: no capability with that id
  • 40924: an install of this capability is already running
  • 40925: the capability is not supported on the current platform / architecture

Plugin summary ​

Listing and installing plugins return this structure. Plugin details add fields on top of it.

FieldTypeDescription
idstringPlugin id
displayNamestringDisplay name
descriptionstringOptional. Description
shortDescriptionstringOptional. Short description
longDescriptionstringOptional. Long description
versionstringOptional. Version
enabledbooleanWhether the plugin is enabled
statestringok / error. A load failure also sets hasErrors
skillCountintegerNumber of skills
mcpServerCountintegerNumber of MCP servers
enabledMcpServerCountintegerNumber of enabled MCP servers
hookCountintegerNumber of hooks
commandCountintegerNumber of commands
hasErrorsbooleanWhether there are errors
sourcestringlocal-path / zip-url / github
originalSourcestringOptional. Original source
githubobjectOptional. GitHub-sourced plugins carry the provenance { owner, repo, ref, installedSha? }, where ref is { kind, value } and kind is branch / tag / sha
originstringmarketplace / custom / unknown
catalogIdstringOptional. Catalog id
installedAtstringInstall time, ISO timestamp

GET /api/v1/plugins ​

Lists installed plugins.

On success, data is { plugins }, where each item is a plugin summary.

GET /api/v1/plugins/{plugin_id} ​

Reads an installed plugin's details and capabilities. Both the skills and mcpServers lists come from the plugin's actual files and manifest. interface.skillOverrides and interface.mcpOverrides override display information only; they do not change invocation names or runtime configuration.

ParameterInTypeDescription
plugin_idpathstringRequired. Installed plugin id
localequerystringOptional. For example en-US or zh-CN. Selects the matching translation from interface.locales and affects only the display text of capabilities; fields without a match fall back to the default interface

On success, data is a plugin summary plus these fields:

FieldTypeDescription
rootstringPlugin root directory
updatedAtstringOptional. Update time
manifestKindstringOptional. Manifest kind: kimi-plugin-root / kimi-plugin-dir
manifestPathstringOptional. Manifest path
skillsarraySkills actually discovered: the invocation name name, plus the optional display name displayName and description description
mcpServersarrayMCP servers declared in the manifest: name, runtime name, enabled state, transport, non-secret connection settings, and optional display name, description, and icon URL
shadowedManifestPathstringOptional. Path of the shadowed manifest
diagnosticsarrayDiagnostics, each { severity, message }, where severity is error / warn / info
  • 40419: no installed plugin with that id

POST /api/v1/plugins ​

Installs a plugin and returns its summary. The request body takes one of two forms: a custom install passes only source; a marketplace install passes marketplaceId plus the expected version information, and does not pass source directly. Neither form accepts other fields.

ParameterInTypeDescription
sourcebodystringRequired for a custom install. An absolute local path, an http(s) ZIP URL, or a GitHub URL. A GitHub URL can pin a version with /tree/<branch-or-sha>, /releases/tag/<tag>, or /commit/<sha>
marketplaceIdbodystringRequired for a marketplace install. Catalog entry id
expectedVersionbodystringFor marketplace installs. The version shown to the user; custom entries without a version may omit it
expectedSha256bodystringFor marketplace installs. The sha256sum shown to the user (64 hex characters). When a ZIP entry declares sha256sum, it must be passed and must match the catalog; local-directory and GitHub entries do not need it

For a marketplace install, the server resolves source, sha256sum, and the expected plugin ID from the same catalog snapshot, verifies the archive before extraction, and checks the manifest ID.

On success, data is a plugin summary.

  • 40001: validation failed, for example source is neither a URL nor an absolute path, or the plugin failed to load
  • 40409: the local path does not exist
  • 40419: no marketplace entry with that id
  • 40934: the catalog entry has changed since the version shown to the user (refresh the catalog and retry)

POST /api/v1/plugins/preview ​

Inspects a marketplace entry's capabilities read-only, without installing the plugin. The server downloads the archive into a temporary directory, verifies its SHA-256 before extraction, checks the manifest ID, and discovers the skills and MCP servers inside. A preview writes no install record, installs no runtime, and does not keep the extracted plugin.

ParameterInTypeDescription
marketplaceIdbodystringRequired. Catalog entry id
expectedVersionbodystringThe version shown to the user
expectedSha256bodystringOptional. The sha256sum shown to the user (64 hex characters); when given, it must match the current catalog
localebodystringOptional. Language of the display text, selected by the same rules as locale in GET /api/v1/plugins/{plugin_id}

On success, data is { skills, mcpServers }, for example:

json
{
  "skills": [{ "name": "<skill name>", "description": "<optional description>" }],
  "mcpServers": [{ "name": "<name in manifest>", "runtimeName": "<runtime name>", "enabled": true, "transport": "stdio" }]
}

Both entry types can also include displayName and description from overrides, and MCP entries can also include iconUrl. MCP entries use the same field structure as GET /api/v1/plugins/{plugin_id}; the example lists only the common fields.

  • 40001: the request, archive, SHA-256, or manifest is invalid
  • 40419: no marketplace entry with that id
  • 40934: the catalog entry has changed since the version shown to the user (refresh the catalog and retry)

GET /api/v1/plugins/marketplace ​

Lists the plugin marketplace catalog merged with live install state. The default catalog URL is derived from the current managed baseURL as ${baseURL}/plugins/marketplace, and built-in capability entries are no longer injected.

The server filters entries by two conditions, and an entry must meet both:

  • Host: the catalog's clients limits an entry to desktop, cli, or both; when omitted, both hosts can use it. Web and Remote Control use the host identity of the connected server.
  • Operating system: platforms filters independently by the operating system the server runs on. An entry is kept when platforms is unset, includes the server's platform, or contains only cloud. Other entries are filtered out, including entries that list cloud together with other platforms but not the server's platform.

Cloud-only entries cannot be installed locally. The legacy kimi-webbridge entry is no longer returned, and Computer Use returns only the wiring plugin for the current platform.

Install records and managed files are still shared under the server's data directory. Entries unavailable to the current host are also hidden from that host's installed list and runtime capabilities.

The server caches the last successfully fetched availability configuration in plugins/availability.json. After a successful catalog refresh, changed client rules hide or restore existing installs without reinstalling them or deleting plugin files.

On success, data is { entries }, each item with the fields below. For the request form of a marketplace install, see POST /api/v1/plugins.

FieldTypeDescription
idstringCatalog entry id, passed as marketplaceId for a marketplace install
tierstringEntry tier: official / curated / third-party. When the entry declares distribution, it is official if distribution.category is official, otherwise curated; without distribution, it is the entry's tier, defaulting to third-party
classificationstringEntry classification: official / third_party. When the entry declares distribution, it is distribution.category; otherwise it is derived from tier: official gives official, anything else gives third_party
displayNamestringDisplay name
descriptionstringOptional. Description, in the language declared by defaultLocale
shortDescriptionstringOptional. Short description
longDescriptionstringOptional. Long description
cliDescriptionstringOptional. CLI description, in the language declared by defaultLocale
homepagestringOptional. Homepage
keywordsstring[]Optional. Keywords
versionstringOptional. Version
sourcestringEntry source
iconUrlstringOptional. Icon URL
sha256sumstringOptional. Archive digest
filenamestringOptional. File name
localeobjectOptional. Per-language translations of displayName, shortDescription, longDescription, and cliDescription
defaultLocalestringOptional. Language of the top-level description / cliDescription
platformsstring[]Optional. darwin / win32 / linux / cloud
distributionobjectOptional. Distribution info: category is official / third_party; the optional region (string), defaultInstall (boolean), weight (number), and userLevel are taken as-is from the catalog
billingobjectOptional. Billing info, taken as-is from the catalog
installedobjectOptional. Present when installed, with the live install state { version?, enabled }
updateAvailablebooleanOptional. true when an update is available, otherwise omitted
capabilityIdstringOptional. Set only by the server, and only when the default marketplace is used: kimi-browser-extension maps to the kimi-webbridge capability, and kimi-cu / kimi-cu-win map to the kimi-cu capability
  • 50001: the marketplace is unreachable or returned an invalid catalog

POST /api/v1/plugins/{plugin_id}:enable ​

Enables an installed plugin. Plugin actions dispatch through one route, POST /api/v1/plugins/{tail}: the tail is parsed as {plugin_id}:{action}, with enable / disable / remove as the actions. A bare id or an unknown action returns 40001 (unsupported action: ...).

ParameterInTypeDescription
plugin_idpathstringRequired. Installed plugin id

On success, data is { ok: true }.

  • 40001: missing or unknown action suffix
  • 40419: no installed plugin with that id

POST /api/v1/plugins/{plugin_id}:disable ​

Disables an installed plugin without removing it. Dispatch works as in :enable.

ParameterInTypeDescription
plugin_idpathstringRequired. Installed plugin id

On success, data is { ok: true }.

  • 40001: missing or unknown action suffix
  • 40419: no installed plugin with that id

POST /api/v1/plugins/{plugin_id}:remove ​

Removes an installed plugin. Dispatch works as in :enable.

ParameterInTypeDescription
plugin_idpathstringRequired. Installed plugin id

On success, data is { ok: true }.

  • 40001: missing or unknown action suffix
  • 40419: no installed plugin with that id

Workspaces ​

These endpoints manage the workspace registry and read and write each workspace's trust state. A workspace is a registered project directory that sessions live in; the trust state decides whether the workspace's project-level MCP config loads. Endpoints that return a workspace use the workspace object.

Method and pathDescription
GET /api/v1/workspacesList registered workspaces
POST /api/v1/workspacesRegister a workspace (each call creates a new entry; retries are deduplicated with idempotency_key)
PATCH /api/v1/workspaces/{workspace_id}Rename, or replace the source folders as a whole
POST /api/v1/workspaces/{workspace_id}/primaryPromote a source folder to the primary directory
GET /api/v1/workspaces/project-config-dirsRead the additional directories in a project's local.toml, read-only
DELETE /api/v1/workspaces/{workspace_id}Unregister a workspace (keeps on-disk content)
GET /api/v1/workspaces/{workspace_id}/trustRead the trust state
POST /api/v1/workspaces/{workspace_id}/trustGrant trust
POST /api/v1/workspaces/{workspace_id}/untrustRevoke trust

Workspace object ​

When a workspace is registered or updated, the server broadcasts the global events event.workspace.created / event.workspace.updated.

FieldTypeDescription
idstringWorkspace id. wd_<slug>_<hash12> for implicit channels (CLI / VS Code entering a directory), wm_<uuid> when created explicitly through POST /api/v1/workspaces
rootstringAbsolute path of the primary directory
namestringDisplay name, 1–100 characters; defaults to the base name of the primary directory
kindstringmanaged: created explicitly, wm_ id; sessions do not merge the project local.toml. implicit: registered implicitly by directory, wd_ id; sessions merge the project local.toml for compatibility with legacy config
additional_dirsstring[]Absolute paths of the registry-managed extra source folders, excluding the project local.toml and ephemeral sources
created_atstringRegistration time, ISO 8601
last_opened_atstringLast time the workspace was opened or re-registered, ISO 8601
session_countintegerNumber of sessions in the workspace

GET /api/v1/workspaces ​

Lists every registered workspace.

On success, data is { items }, where each item is a workspace object.

POST /api/v1/workspaces ​

Registers a new workspace and returns it. Every call creates a new entry (wm_<uuid> id). Even when the same path is already another workspace's primary directory, the call does not merge into the existing entry or warn.

When a client resubmits (network retry, double click), it should send the same idempotency_key. The server deduplicates by key and returns the entry created the first time.

ParameterInTypeDescription
rootbodystringRequired. Absolute path of an existing directory, used as the primary directory
namebodystringDisplay name, 1–100 characters. Default the base name of the primary directory
additional_dirsbodystring[]Extra source folders, at most 64 items. Each item resolves by the add-dir rules (absolute path, relative to the primary directory, or ~ expansion), must exist and be a directory, and must not duplicate the primary directory or another item
idempotency_keybodystringClient-generated idempotency key, 1–200 characters. Retries with the same key return the workspace created the first time

On success, data is a workspace object.

  • 40001: root is missing or not an absolute path, or another request validation failed (details lists the field)
  • 40006: additional_dirs contains duplicates or the primary directory itself. msg is Duplicate source folder: <actual path>; details is [{ "path": "additional_dirs.N", "directory": "<resolved absolute path>" }], where path is the location of the request field and directory is the duplicated directory
  • 40409: root or a path in additional_dirs does not exist or is not a directory

PATCH /api/v1/workspaces/{workspace_id} ​

Updates a workspace's display name and/or source folders; the primary directory cannot be changed. At least one of name and additional_dirs is required. additional_dirs is a whole-list replacement: submit the full edited list, or omit the field to keep it unchanged.

ParameterInTypeDescription
workspace_idpathstringRequired. Workspace id
namebodystringNew display name, 1–100 characters
additional_dirsbodystring[]Full replacement list of extra source folders, resolved and validated as in POST /api/v1/workspaces

On success, data is a workspace object.

  • 40001: both fields are missing, or another request validation failed (details explains each field)
  • 40006: duplicate entries, or an entry equal to the primary directory; msg, details.path, and details.directory mean the same as in POST /api/v1/workspaces
  • 40409: a path in additional_dirs does not exist or is not a directory
  • 40410: workspace not found

POST /api/v1/workspaces/{workspace_id}/primary ​

Promotes a source folder in the directory set to the primary directory. The server performs an atomic swap: the path becomes the new root, and the previous primary directory moves into additional_dirs. The workspace id and session bucket do not change, and all sessions are kept. local.toml follows the primary directory, so after the swap the additional directories in the previous primary directory's local.toml are no longer merged.

For existing sessions that run on the local environment without an explicit environmentCwd, the default working directory and relative paths of later tool calls follow the new primary directory. An explicit environmentCwd and remote environment bindings keep their configured directory.

Additional directories only widen the allowed access scope; they are not candidate roots for relative paths, so access them with absolute paths or an explicit cwd. Registered tools stay available during the swap, and the workspace's existing trust decision is kept across restarts.

ParameterInTypeDescription
workspace_idpathstringRequired. Workspace id
pathbodystringRequired. Directory to promote, resolved by the add-dir rules; must be in the current directory set (root ∪ additional_dirs)

On success, data is a workspace object.

  • 40001: path is not in the directory set
  • 40409: path does not exist or is not a directory
  • 40410: workspace not found

GET /api/v1/workspaces/project-config-dirs ​

Returns workspace.additional_dir from the given project's local.toml, read-only. The result is resolved to absolute paths, deduplicated, and excludes root itself. The endpoint modifies neither the registry nor local.toml. Clients can use it to merge a project's legacy config into the create or edit workspace form, taking effect on save.

The server walks up from root to the first directory that contains .git and uses it as the project root (or root itself when none is found), then reads .kimi-code/local.toml there. A missing local.toml returns an empty array. Malformed TOML or a configured directory that no longer exists fails the request instead of returning an empty config.

ParameterInTypeDescription
rootquerystringRequired. Absolute path of the project's primary directory

On success, data is { additional_dirs: string[] }.

  • 40001: root is missing or empty; the structure of local.toml is invalid (for example workspace.additional_dir is not an array of strings); or a directory configured there does not exist or is not a directory
  • 50001: local.toml is not valid TOML, or reading it failed

DELETE /api/v1/workspaces/{workspace_id} ​

Unregisters a workspace. Only the registry entry is removed; the directory on disk is untouched.

ParameterInTypeDescription
workspace_idpathstringRequired. Workspace id

On success, data is { deleted: true }.

  • 40410: workspace not found

GET /api/v1/workspaces/{workspace_id}/trust ​

Reads the workspace's trust state. The trust state decides whether project-level MCP config loads for the workspace.

ParameterInTypeDescription
workspace_idpathstringRequired. Workspace id

On success, data is { trusted }.

  • 40410: workspace not found

POST /api/v1/workspaces/{workspace_id}/trust ​

Marks the workspace as trusted and loads its project-level MCP config.

ParameterInTypeDescription
workspace_idpathstringRequired. Workspace id

On success, data is { trusted: true }.

  • 40410: workspace not found

POST /api/v1/workspaces/{workspace_id}/untrust ​

Revokes the persisted trust records associated with the current directory set. Unless a process or config override keeps the workspace trusted, its project-level MCP config is also unloaded.

ParameterInTypeDescription
workspace_idpathstringRequired. Workspace id

On success, data is { trusted }, the effective trust state after revocation. It is normally false, but stays true when KIMI_CODE_TRUST_WORKSPACE or [workspace] require_trust = false applies.

  • 40410: workspace not found

File uploads ​

These endpoints upload files for later reference (for example as prompt attachments), and download or delete uploaded files.

Method and pathDescription
POST /api/v1/filesMultipart upload (file field, optional name and expires_in_sec); returns file metadata
GET /api/v1/files/{file_id}Download (binary; errors use real HTTP status codes)
DELETE /api/v1/files/{file_id}Delete

POST /api/v1/files ​

Uploads a file as multipart/form-data.

ParameterInTypeDescription
filebodybinaryRequired. The multipart file part
namebodystringStored display name. Default the uploaded file name
expires_in_secbodynumberSeconds until the file expires (non-negative). Default never expires

On success, data is the file metadata:

FieldTypeDescription
idstringFile id, used to download and delete the file
namestringDisplay name
media_typestringTaken from the upload's content type
sizeintegerFile size
created_atstringUpload time
expires_atstringOptional. Expiry time
  • 40001: the multipart body has no file field

GET /api/v1/files/{file_id} ​

Downloads an uploaded file. The response is a binary stream that supports range requests but does not handle If-None-Match. Failures use real HTTP status codes; see Binary and streaming endpoints.

ParameterInTypeDescription
file_idpathstringRequired. File id from the upload response
  • 40407 (HTTP 404): no file with that id (including an expired file)

DELETE /api/v1/files/{file_id} ​

Deletes an uploaded file.

ParameterInTypeDescription
file_idpathstringRequired. File id from the upload response

On success, data is { deleted: true }.

  • 40407 (HTTP 404): no file with that id

GUI store ​

A server-backed key/value store whose interface mirrors the browser's localStorage, with data persisted under the server's home directory. The web UI uses it to keep cross-client UI state. Values are opaque strings, and serialization is the caller's job.

Method and pathDescription
GET /api/v1/gui/store/lengthNumber of stored keys
GET /api/v1/gui/store/getItemRead a value by key
POST /api/v1/gui/store/setItemWrite a value by key
POST /api/v1/gui/store/removeItemDelete a value by key
POST /api/v1/gui/store/clearDelete all values

GET /api/v1/gui/store/length ​

Returns the number of stored keys, mirroring localStorage.length. No parameters.

On success, data is { length }.

GET /api/v1/gui/store/getItem ​

Reads one value, mirroring localStorage.getItem.

ParameterInTypeDescription
keyquerystringRequired. Key to read, 1–256 characters

On success, data is { value }: the stored string, or null when the key does not exist.

POST /api/v1/gui/store/setItem ​

Writes one value, mirroring localStorage.setItem.

ParameterInTypeDescription
keybodystringRequired. Key to write, 1–256 characters
valuebodystringRequired. Value to store

On success, data is null.

POST /api/v1/gui/store/removeItem ​

Deletes one value, mirroring localStorage.removeItem.

ParameterInTypeDescription
keybodystringRequired. Key to delete, 1–256 characters

On success, data is null.

POST /api/v1/gui/store/clear ​

Deletes every stored value, mirroring localStorage.clear. No parameters.

On success, data is null.

Global search and other endpoints ​

Cross-session full-text search, the list of live WebSocket connections, and entry points to other endpoints.

Method and pathDescription
POST /api/v1/searchCross-session full-text search; mode is terms (default) or literal (exact substring); paginated with page_token
GET /api/v1/connectionsList live WebSocket connections
GET /api/v1/sessionsSession list and grouped queries; see GET /api/v1/sessions
POST /api/v1/sessions:archiveBatch-archive sessions; see POST /api/v1/sessions:archive
POST /api/v1/sessions:restoreBatch-restore archived sessions; see POST /api/v1/sessions:restore
/api/v1/mcp/*Unified MCP management plane; see MCP management
/api/v1/debug/*Reflection debug RPC; mounted only with --debug-endpoints on loopback, not part of the stable protocol

POST /api/v1/search ​

Cross-session full-text search over user messages, assistant replies, and session titles, backed by the server's persistent search index.

A search scoped to one session with container.session_id also uses the index. So text that a running step is still generating becomes searchable only after the step is saved and the index catches up; a view that is still catching up is marked by index_state.stale.

ParameterInTypeDescription
querybodystringRequired. Search text
modebodystringterms (default) / literal
opbodystringHow terms combine in terms mode: AND (default) / OR
containerbodyobjectRestrict the search to { session_id?, agent_id? }
rolebodystringOnly user / assistant / title hits
start_timebodyintegerOnly hits at or after this time (epoch milliseconds)
end_timebodyintegerOnly hits at or before this time (epoch milliseconds)
sortbodystringscore (default) / time_desc / time_asc; literal mode ignores it and always returns newest first
page_sizebodyintegerHits per page, 1–50. Default 20
page_tokenbodystringToken returned by the previous page's response

terms mode tokenizes the query (ASCII words plus CJK n-grams), deduplicates the terms, and matches at most 32 terms against the inverted index. literal mode is an exact substring search with zero false positives.

Page tokens pin the index generation and the query conditions, so an index rebuild or a changed query invalidates them.

On success, data has these fields:

FieldTypeDescription
itemsarrayHits; item fields in the table below
has_morebooleanWhether there is a next page
page_tokenstringOptional. Token for the next page
incompletestringPresent only on over-budget pages: candidate_cap / postings_budget / deadline
index_state.statestringbuilding / ready / readonly
index_state.indexed_sessionsintegerNumber of indexed sessions
index_state.total_sessionsintegerTotal number of sessions
index_state.documentsintegerNumber of documents
index_state.stalebooleanOptional. Marks a lagging view that is still catching up
index_state.degradedstringOptional. Message of the most recent refresh failure

Fields of each items entry:

FieldTypeDescription
session_idstringSession id
workspace_idstringWorkspace id
session_titlestringSession title
agent_idstringAgent id
rolestringuser / assistant / title
snippetstringMatched snippet
timenumberHit time
turnintegerOptional. Turn
step_idstringOptional. Step id
scorenumberRelevance score
  • 40001: body validation failed, the query is unusable (empty, or more than 32 terms), or the page token is invalid

GET /api/v1/connections ​

Lists the WebSocket clients currently connected to this server, oldest connection first. No parameters.

On success, data is { connections }, each item with these fields:

FieldTypeDescription
idstringConnection id
connected_atstringConnection time, ISO 8601
remote_addressstring | nullRemote address; null when unknown
user_agentstring | nullUser-Agent; null when unknown
subscriptionsstring[]Ids of the sessions this connection subscribes to

MCP management ​

/api/v1/mcp/* is the server's unified MCP management plane. It is independent of any session and manages the MCP server registry itself. It covers CRUD on user-level config (each entry is validated before it is written), connection tests, a locator-addressed inspection catalog, per-server auth status, and the full OAuth flow.

Method and pathDescription
GET /api/v1/mcp/serversList every known MCP server
GET /api/v1/mcp/servers/{name}Get one MCP server by runtime name
POST /api/v1/mcp/serversAdd an MCP server to the user-level mcp.json
PUT /api/v1/mcp/servers/{name}Replace a user-level entry
DELETE /api/v1/mcp/servers/{name}Delete a user-level entry
POST /api/v1/mcp/servers:testProbe a real connection to one MCP server
POST /api/v1/mcp/servers:inspectLocator-addressed catalog with batched connection probes
GET /api/v1/mcp/auth-statusesOAuth state of each MCP server in the catalog
POST /api/v1/mcp/auth:beginBegin an interactive OAuth flow
POST /api/v1/mcp/auth:completeWait for the browser callback and finish the code exchange
POST /api/v1/mcp/auth:cancelTerminate a begun OAuth flow
POST /api/v1/mcp/auth:resetClear an MCP server's stored credentials

The management plane uses two addressing schemes:

  • Runtime name: the CRUD endpoints and servers:test use a plain runtime name.
  • Locator: the inspection and OAuth endpoints use a locator, because a plugin entry and a file entry can share one runtime name. A file-layer entry's locator is { "source": "global", "name" }, and a plugin-manifest entry's is { "source": "plugin", "pluginId", "serverName" }.

Inspection results also carry a stable serverId: global:<name> or plugin:<pluginId>:<serverName> (URL-encoded).

Every endpoint except auth:complete and auth:cancel accepts an optional cwd: in the request body for servers:test and servers:inspect, and as a query parameter for the rest (including auth:begin and auth:reset). Without it, the catalog covers only the user-level file and plugin manifests. With it, the project-root and project-local layers of that directory join in, but only when the workspace is trusted; otherwise the project layers are skipped. For servers:test on a stdio server, cwd is also the child process's working directory.

Connection probes and OAuth calls wait until the server configuration has finished loading.

GET /api/v1/mcp/servers ​

Lists every MCP server the management plane knows about.

ParameterInTypeDescription
cwdquerystringInclude the project layers of this directory (must be trusted)

On success, data is an array of managed MCP servers, each with these fields:

FieldTypeDescription
namestringRuntime name
configobjectMutable entries carry the full config so edit UIs can prefill it; read-only entries are redacted to sorted key lists (envKeys / headerKeys) and never disclose secret values
sourcestringglobal (a config-file layer, including the user-level file and project layers) or plugin (a plugin manifest). The schema also has caller, which is currently never returned
originstringWhere the entry is defined: a file path or a plugin id
mutablebooleanOnly user-level entries are mutable; plugin and project-layer entries are read-only
pluginobjectPresent only on plugin entries: { id, name }
  • 40001: validation failure

GET /api/v1/mcp/servers/{name} ​

Gets one MCP server by runtime name.

ParameterInTypeDescription
namepathstringRequired. Runtime name of the MCP server
cwdquerystringInclude the project layers of this directory (must be trusted)

On success, data is a single managed MCP server, with the same fields as GET /api/v1/mcp/servers.

  • 40001: validation failure
  • 40408: no MCP server with that name

POST /api/v1/mcp/servers ​

Adds an MCP server to the user-level mcp.json. The request body is a full server config including name. transport (stdio / http / sse) determines the config shape, and the config is validated before it is written.

A write that collides with a same-named project-layer entry is rejected because that entry is read-only; edit the file that defines it instead. Project layers join in only when cwd is passed and that directory is trusted, so this collision is checked only then. A collision with a same-named plugin entry does not block the write, and the new file entry shadows the plugin entry.

ParameterInTypeDescription
cwdquerystringInclude the project layers of this directory (must be trusted); the returned list also includes project layers

On success, data is the refreshed MCP server list, with the same fields as GET /api/v1/mcp/servers.

  • 40001: validation failure, or the target entry is read-only

PUT /api/v1/mcp/servers/{name} ​

Replaces a user-level entry. The request body is the same config as in POST /api/v1/mcp/servers, but without name, because the path names the entry. Collisions with same-named entries follow the same rules.

ParameterInTypeDescription
namepathstringRequired. Runtime name of the entry to replace
cwdquerystringInclude the project layers of this directory (must be trusted)

On success, data is the refreshed MCP server list.

  • 40001: validation failure, or the target entry is read-only
  • 40408: no MCP server with that name

DELETE /api/v1/mcp/servers/{name} ​

Deletes a user-level entry. No request body.

ParameterInTypeDescription
namepathstringRequired. Runtime name of the entry to delete
cwdquerystringInclude the project layers of this directory (must be trusted)

On success, data is the refreshed MCP server list.

  • 40001: validation failure, or the target entry is read-only
  • 40408: no MCP server with that name

POST /api/v1/mcp/servers:test ​

Probes a real connection to one MCP server and persists nothing. Pass name to probe a registry entry (plugin and trusted project layers included), or pass server to probe an inline config as-is. Exactly one of the two must be passed.

ParameterInTypeDescription
namebodystringRuntime name of a registry entry
serverbodyobjectInline config to probe as-is; must include name
cwdbodystringUsed to include project layers; also the working directory of a stdio child process

On success, data is { success, output }: when the connection succeeds, output lists the server's available tools; otherwise it carries the failure message.

  • 40001: both or neither target form passed, the inline config is invalid, or the runtime name is shared by multiple enabled MCP servers
  • 40408: no MCP server with that name

POST /api/v1/mcp/servers:inspect ​

Returns the locator-addressed catalog (with redacted configs) and runs a batched real-connection probe of every OAuth candidate. A probe that hits an expired grant may refresh or invalidate the stored credentials.

ParameterInTypeDescription
targetsbodyarrayLocators that narrow the catalog; when omitted, every MCP server is inspected
cwdbodystringInclude the project layers of this directory (must be trusted)

On success, data is an array of inspection results, each with these fields:

FieldTypeDescription
serverIdstringStable identifier; format in MCP management
locatorobjectThe entry's locator
runtimeNamestringRuntime name
canonicalUrlstringOptional. Credential URL of a remote server
originstringEntry source, with the same values as source in GET /api/v1/mcp/servers
configobjectRedacted config
enabledbooleanWhether the entry is enabled
editablebooleanWhether the entry is editable
authStatusstringnot-applicable / bearer-token / oauth-required / oauth-authorized / oauth-expired / unavailable. A runtime name shared by multiple enabled MCP servers cannot be probed unambiguously and reports unavailable
checkedAtnumberOptional. Check time
errorstringOptional. Error explanation, for example when the runtime name is shared
  • 40001: validation failure
  • 40408: a locator in targets matches no entry

GET /api/v1/mcp/auth-statuses ​

Reads the OAuth state of each MCP server in the registry catalog. When only the auth dimension is needed, it is lighter than servers:inspect. Verification probes may refresh or invalidate stored credentials.

ParameterInTypeDescription
cwdquerystringInclude the project layers of this directory (must be trusted)
verifyquerystringtrue: verify every OAuth candidate through a real connection. false: fully offline, classifying only from config and stored tokens. Omitted: keep implicit OAuth detection, probing only unpinned remote servers without stored credentials

On success, data is an array of { name, authStatus }, with the same authStatus values as servers:inspect.

POST /api/v1/mcp/auth:begin ​

Begins an interactive OAuth flow for a remote MCP server. The target must use a remote transport (http / sse) and must not carry a static bearer token; static headers are allowed only when the config explicitly sets auth: "oauth".

ParameterInTypeDescription
locatorbodyobjectRequired. The whole request body is the target's locator
cwdquerystringOptional. Include the project layers of this directory (must be trusted)

On success, data.status is one of two values:

FieldTypeDescription
statusstringauthorization-required: authorization is needed. already-authorized: a grant already exists, and no other fields are present
flowIdstringauthorization-required only: flow id, used by auth:complete and auth:cancel
authorizationUrlstringauthorization-required only: open this URL in a browser to grant access
  • 40001: validation failure; the MCP server cannot use OAuth (stdio transport, a static bearer token, or static headers without auth: "oauth"); or the runtime name is shared by multiple enabled MCP servers
  • 40408: the locator matches no entry
  • 40929: the OAuth flow itself failed

POST /api/v1/mcp/auth:complete ​

Waits for the browser callback of a begun flow and finishes the code exchange. The wait defaults to 15 minutes and can be overridden with timeoutMs; an idle flow expires after 15 minutes regardless. Closing the HTTP connection on the client side aborts the wait.

ParameterInTypeDescription
flowIdbodystringRequired. Flow id returned by auth:begin
timeoutMsbodyintegerWait time in milliseconds, from 1 to 2³¹−1. Default 15 minutes

On success, data is null.

  • 40001: validation failure, including an unknown flowId or an out-of-range timeoutMs
  • 40929: the OAuth flow itself failed

POST /api/v1/mcp/auth:cancel ​

Terminates a begun flow without finishing it. Unknown flows are ignored.

ParameterInTypeDescription
flowIdbodystringRequired. Id of the flow to terminate

On success, data is null.

  • 40001: validation failure
  • 40929: the OAuth flow itself failed

POST /api/v1/mcp/auth:reset ​

Clears an MCP server's stored credentials. The invalidation event reaches live sessions.

ParameterInTypeDescription
locatorbodyobjectRequired. The whole request body is the target's locator
cwdquerystringOptional. Include the project layers of this directory (must be trusted)

On success, data is null.

  • 40001: validation failure; the target uses stdio transport; or the runtime name is shared by multiple enabled MCP servers
  • 40408: the locator matches no entry
  • 40929: the OAuth flow itself failed