DevelopersReference
Skills
The org's skill library over the built-ins, as documents with versions.
Base URL https://api.showpilot.com/v1. Every call needs Authorization: Bearer <api key>; see Authentication.
Every skill the agents can run
GET /skills
Scope: agents:read. Operation id: listSkills.
The org's library over the built-ins; an org row wins its slug, a removed built-in is absent. Built-ins read as source: builtin, version 0.
Example request
curl "https://api.showpilot.com/v1/skills" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Runs against your sandbox with a test key.
Response
The skills.
| Field | Type | Always | Meaning |
|---|---|---|---|
items | array of SkillDocument | yes |
SkillDocument
| Field | Type | Always | Meaning |
|---|---|---|---|
slug | string | yes | |
name | string | yes | |
description | string | yes | |
body | string | yes | Markdown the agent consults. |
source | builtin · fork · custom | yes | |
version | integer | yes | 0 for an unforked built-in. |
updatedAt | string or null (date-time) | yes |
Errors
| Status | When |
|---|---|
| 401 | No key, or an unknown or revoked key. Code unauthorized. |
| 403 | A valid key without the operation's scope (code insufficient-scope), or a plan without API access (code plan-api-off). |
| 429 | The key's bucket is empty. Code rate-limited; wait the Retry-After seconds. |
One skill as a document
GET /skills/{slug}
Scope: agents:read. Operation id: getSkill.
Parameters
| Name | In | Type | Meaning |
|---|---|---|---|
slug | path | string | The skill's slug. |
Example request
curl "https://api.showpilot.com/v1/skills/qualification-rubric" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Runs against your sandbox with a test key.
Response
The skill.
SkillDocument
| Field | Type | Always | Meaning |
|---|---|---|---|
slug | string | yes | |
name | string | yes | |
description | string | yes | |
body | string | yes | Markdown the agent consults. |
source | builtin · fork · custom | yes | |
version | integer | yes | 0 for an unforked built-in. |
updatedAt | string or null (date-time) | yes |
Errors
| Status | When |
|---|---|
| 401 | No key, or an unknown or revoked key. Code unauthorized. |
| 403 | A valid key without the operation's scope (code insufficient-scope), or a plan without API access (code plan-api-off). |
| 404 | No object with that id in this workspace. Code not-found. |
| 429 | The key's bucket is empty. Code rate-limited; wait the Retry-After seconds. |
Apply a skill edit
PUT /skills/{slug}
Scope: agents:write. Operation id: applySkill.
Writes the body (and name or description when given) when
baseVersion matches; a built-in is forked on its first write
(baseVersion 0, response 201), a new slug is created the same way.
Otherwise 409 stale. Lint errors refuse the write with 400 lint-failed. Skill bodies are live: the agent runs the new text on
its next turn.
Parameters
| Name | In | Type | Meaning |
|---|---|---|---|
Idempotency-Key | header | string | Any unique string, up to 200 characters, chosen by the caller. A retry with the same key and the same request replays the stored response (with the header Idempotent-Replayed set to true); the same key with a different request is refused. Keys are remembered for 24 hours. |
slug | path | string | The skill's slug. |
Example request
curl "https://api.showpilot.com/v1/skills/qualification-rubric" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Runs against your sandbox with a test key.
Response
The skill as written.
SkillDocument
| Field | Type | Always | Meaning |
|---|---|---|---|
slug | string | yes | |
name | string | yes | |
description | string | yes | |
body | string | yes | Markdown the agent consults. |
source | builtin · fork · custom | yes | |
version | integer | yes | 0 for an unforked built-in. |
updatedAt | string or null (date-time) | yes |
Errors
| Status | When |
|---|---|
| 400 | The edit has lint errors. Code lint-failed; problems lists them. |
| 401 | No key, or an unknown or revoked key. Code unauthorized. |
| 403 | A valid key without the operation's scope (code insufficient-scope), or a plan without API access (code plan-api-off). |
| 404 | No object with that id in this workspace. Code not-found. |
| 409 | The document changed since the baseVersion you read. Code stale; currentVersion at the top level says what to re-read. |
| 429 | The key's bucket is empty. Code rate-limited; wait the Retry-After seconds. |
Lint and diff a skill edit, writing nothing
POST /skills/{slug}/propose
Scope: agents:read. Operation id: proposeSkill.
Parameters
| Name | In | Type | Meaning |
|---|---|---|---|
slug | path | string | The skill's slug. |
Example request
curl "https://api.showpilot.com/v1/skills/qualification-rubric/propose" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Runs against your sandbox with a test key.
Response
The proposal.
Proposal
What an apply would do, without doing it.
| Field | Type | Always | Meaning |
|---|---|---|---|
baseVersion | object | yes | The version to pass to apply. |
diff | object | yes | One entry per changed field. |
problems | array of LintProblem | yes | |
applicable | boolean | yes | False when any problem is an error. |
LintProblem
| Field | Type | Always | Meaning |
|---|---|---|---|
path | string | yes | The field the problem is in. |
code | string | yes | empty, too-long, vocab-demo, vocab-project, vocab-folio, unknown-skill, tool-missing. |
message | string | yes | |
severity | error · warning | yes |
Errors
| Status | When |
|---|---|
| 400 | A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code invalid-request. |
| 401 | No key, or an unknown or revoked key. Code unauthorized. |
| 403 | A valid key without the operation's scope (code insufficient-scope), or a plan without API access (code plan-api-off). |
| 429 | The key's bucket is empty. Code rate-limited; wait the Retry-After seconds. |