API Reference
Prompts
The prompts, prompt repos and GitHub connections endpoints.
The prompt endpoints manage inline prompts, GitHub prompts, the prompt repos they come from, and GitHub connections. Each group has its own scopes. Inline prompts, prefixed ip_, are changed through the API; GitHub prompts, prefixed pf_, are read-only and change in their repository. See Managing Prompts.
Prompts
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /v1/prompts | List prompts. Filter with source, type or prompt_repo_id. Paginated. | prompts:read |
| POST | /v1/prompts | Create an inline prompt from name, type and body. Returns 201. Accepts dry_run and an Idempotency-Key. | prompts:write |
| GET | /v1/prompts/{id} | Get a prompt with its body and variables. | prompts:read |
| PATCH | /v1/prompts/{id} | Change name or body. A changed body saves a new version. Accepts dry_run. | prompts:write |
| DELETE | /v1/prompts/{id} | Delete an inline prompt that no router binds. Accepts dry_run. | prompts:delete |
| GET | /v1/prompts/{id}/versions | List versions, or commits for a GitHub prompt, newest first. Paginated. | prompts:read |
| GET | /v1/prompts/{id}/versions/{version} | Get one version by number, or one commit by SHA. | prompts:read |
| POST | /v1/prompts/{id}/versions/{version}/restore | Make an earlier inline version current, as a new version. Takes no body. Accepts dry_run. | prompts:write |
| GET | /v1/prompts/{id}/routers | List the routers bound to the prompt. | prompts:read |
| GET | /v1/prompts/{id}/tags | List the prompt's tags. | prompts:read |
| POST | /v1/prompts/{id}/tags | Add a tag, sent as tag. | prompts:write |
| DELETE | /v1/prompts/{id}/tags/{key} | Remove a tag. | prompts:delete |
A text prompt's body is a string, and a chat prompt's body is an array of role and content messages. A prompt's type is fixed. Writes are conditional on the prompt's ETag.
Prompt repos
A prompt repo connects a repository and branch through a connected GitHub account, and tracks files from it. Each tracked .md or .json file becomes a GitHub prompt:
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /v1/prompt-repos | List prompt repos. Paginated. | prompt_repos:read |
| POST | /v1/prompt-repos | Connect repository (owner/repo) and branch under a name, tracking up to 100 file_paths. Returns 201. Accepts dry_run and an Idempotency-Key. | prompt_repos:write |
| GET | /v1/prompt-repos/{id} | Get a prompt repo. | prompt_repos:read |
| PATCH | /v1/prompt-repos/{id} | Rename it. Accepts dry_run. | prompt_repos:write |
| DELETE | /v1/prompt-repos/{id} | Disconnect it and remove its prompts. Returns files_deleted. Accepts dry_run. | prompt_repos:delete |
| GET | /v1/prompt-repos/{id}/files | List tracked files, each with its prompt id and sync status. Paginated. | prompt_repos:read |
| POST | /v1/prompt-repos/{id}/files | Track one file, sent as path. Accepts dry_run. | prompt_repos:write |
| DELETE | /v1/prompt-repos/{id}/files | Stop tracking the file named in the path query parameter. Accepts dry_run. | prompt_repos:delete |
| GET | /v1/prompt-repos/{id}/commits | List commits on the branch, optionally only those touching file_path. Paginated. | prompt_repos:read |
| GET | /v1/prompt-repos/{id}/tags | List the repo's tags. | prompt_repos:read |
| POST | /v1/prompt-repos/{id}/tags | Add a tag, sent as tag. Accepts dry_run. | prompt_repos:write |
| DELETE | /v1/prompt-repos/{id}/tags/{key} | Remove a tag. Accepts dry_run. | prompt_repos:delete |
GitHub connections
The GitHub connections endpoints read and remove connected GitHub accounts:
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /v1/github/connections | List connected GitHub accounts. Paginated. | github:read |
| GET | /v1/github/connections/{login} | Get one connection by its GitHub login. | github:read |
| DELETE | /v1/github/connections/{login} | Disconnect a GitHub account. Accepts dry_run. | github:delete |
GitHub accounts are connected in the dashboard. See GitHub Prompt.
Errors
| Code | Status | Meaning |
|---|---|---|
prompt_not_found | 404 | The id matches no prompt. |
revision_not_found | 404 | The prompt has no such version. |
invalid_revision | 400 | An inline version is not a positive whole number. |
unexpected_body | 400 | A restore sent a body. |
source_read_only | 409 | A write names a GitHub prompt. |
prompt_in_use | 409 | A delete names a prompt that routers bind. |
prompt_repo_not_found | 404 | The id matches no prompt repo. |
prompt_repo_exists | 409 | The repository and branch are already connected. |
github_repo_not_found | 404 | The connected account cannot find the repository or branch. |
file_not_found | 404 | The file is not tracked. |
invalid_file_path | 400 | The path is absolute, climbs out of the repository, is too long, or is not a .md or .json file. |
github_not_connected | 424 | The repository owner's GitHub account is not connected. |
github_error | 502 | GitHub returned an error. |
connection_not_found | 404 | No connected GitHub account has that login. |
use_sub_collection | 400 | An inline prompt PATCH sends tags, or a prompt repo PATCH sends files or tags. They change through their own endpoints; a GitHub prompt PATCH returns source_read_only first. The valid field of the error lists the endpoint path template, such as /v1/prompts/{id}/tags; {id} is not replaced with the object id. |