docs: document detailed parameters for all server API endpoints - #3155
Conversation
|
commit: |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 46c96823f4
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
|
||
| #### `POST /api/v1/models/{model_id}:set_default` | ||
|
|
||
| Sets the global `default_model` to an existing alias. An alias id contains `/`, so URL-encode it in the path — for example `POST /api/v1/models/my-provider%2Fkimi-for-coding:set_default`. |
There was a problem hiding this comment.
For configurations that use a bare model-table key such as turbo, this instruction incorrectly says every alias contains / and implies callers should construct a provider_id/model value. The route passes the decoded path ID directly to setDefaultModel, and packages/kap-server/test/modelCatalog.test.ts demonstrates /api/v1/models/turbo:set_default; only aliases created through the provider-management endpoints are forced into the provider_id/model form. Clarify that model_id is the exact configured alias key and encode / only when that key contains one; make the same correction in the Chinese mirror.
AGENTS.md reference: docs/AGENTS.md:L19-L21
Useful? React with 👍 / 👎.
| | `session_id` | path | string | **Required.** Session id | | ||
| | `skill_name` | path | string | **Required.** Name of the skill to activate | | ||
| | `args` | body | string | Free-form arguments handed to the skill, like the text after a slash command | | ||
| | `attachments` | body | array | Media parts attached to the activation: image, video, or file objects whose `source.kind` is `url` / `base64` / `file` / `session_media` | |
There was a problem hiding this comment.
When activating a skill with a type: "file" attachment, this description leads clients to send source.kind, but activateSkillAttachmentSchema uses fileContentSchema, whose required fields are the top-level file_id, name, media_type, and size; only image and video attachments have a source object. Document the two shapes separately (or link to the prompt content-part table) in both locale mirrors so the advertised request can pass validation.
AGENTS.md reference: docs/AGENTS.md:L19-L21
Useful? React with 👍 / 👎.
1 participant
Related Issue
No linked issue — internal docs task.
Problem
The Server API reference page (
docs/{en,zh}/reference/server-api.md) listed every kap-server endpoint as a one-line summary table only. Readers could not construct a request from the page: query parameters, request body fields, response shapes, and endpoint-specific error codes were not documented. Several endpoints and two whole groups (capabilities, plugins, GUI store, session runtime/title/media,oauth/region,workspace/fs:suggest) were missing from the page entirely.What changed
Expanded the REST reference so every v1+v2 endpoint (except the unstable
/api/v1/debug/*reflection RPC) has a per-endpoint subsection, in both locales:datashape, and the endpoint's specific error codes.:{action}dispatcher endpoints are expanded into concrete subsections (session:fork/:compact/:undo/:abort/:btw/:archive/:restore, prompt:steer/:abort, question:dismiss, task:cancel, provider collection actions, plugin:enable/:disable/:remove, all 13fs:{action}operations, ...).Capabilities and pluginsandGUI store, and the missing endpoints listed above./openapi.json//asyncapi.jsonremain the normative machine-readable schema.Parameter facts were extracted from the server's generated OpenAPI document (same zod schemas as runtime validation); semantics were written from the route sources. Where the generated spec and the source disagreed, the page follows the source and says so (e.g. boolean list filters only appear required in the spec due to a zod-preprocess projection;
:dismissanswers envelope code40909on success; fields accepted by the schema but not applied are marked as such).Checklist
/approve). — N/A, internal docs task.gen-changesetsskill, or this PR needs no changeset. — No changeset: docs-only change that never enters the shipped artifact.gen-docsskill, or this PR needs no doc update. — This PR is the doc update.