Agents

Base URL https://api.showpilot.com/v1. Every call needs Authorization: Bearer <api key>; see Authentication.

List agents, newest first

GET /agents

Scope: agents:read. Operation id: listAgents.

Parameters

Name	In	Type	Meaning
`limit`	query	integer	Page size, 1 to 200. Default 50.
`cursor`	query	string	The `nextCursor` from the previous page. Opaque; never build one.

Example request

curl "https://api.showpilot.com/v1/agents?limit=50" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

One page of agents.

Field	Type	Always	Meaning
`items`	array of Agent	yes
`nextCursor`	NextCursor	yes

Agent

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`publicId`	string	yes	The id in the embed tag.
`name`	string	yes
`title`	string or null	yes
`published`	boolean	yes	A revision is live and serving visitors.
`publishedVersion`	integer or null	yes
`publishedAt`	string or null (date-time)	yes
`skills`	array of string	yes	Slugs of the skills attached to the agent.
`view`	string or null	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

NextCursor

Pass as cursor for the next page; null on the last page.

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.

One agent

GET /agents/{id}

Scope: agents:read. Operation id: getAgent.

Parameters

Name	In	Type	Meaning
`id`	path	string	The agent's UUID or public id.

Example request

curl "https://api.showpilot.com/v1/agents/2f7c1d4e-9b3a-4c6d-8e5f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The agent with its welcome message, tone and company name.

Every field of Agent, plus:

Field	Type	Always
`welcomeMessage`	string or null	no
`tone`	string or null	no
`companyName`	string or null	no

Agent

Field	Type	Always	Meaning
`id`	string (uuid)	yes
`publicId`	string	yes	The id in the embed tag.
`name`	string	yes
`title`	string or null	yes
`published`	boolean	yes	A revision is live and serving visitors.
`publishedVersion`	integer or null	yes
`publishedAt`	string or null (date-time)	yes
`skills`	array of string	yes	Slugs of the skills attached to the agent.
`view`	string or null	yes
`createdAt`	string (date-time)	yes
`updatedAt`	string (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.

The agent's script as a document

GET /agents/{id}/script

Scope: agents:read. Operation id: getAgentScript.

The authored prompt text (instructions, persona, behavior, welcome message, tone) and the skills the agent runs. version is the base an apply must carry. include=context adds what an author needs: the agent's facts, every resolvable skill, knowledge bases, forms, offers, tours, and the active script's prompts and modules.

Parameters

Name	In	Type	Meaning
`id`	path	string	The agent's UUID or public id.
`include`	query	`context`

Example request

curl "https://api.showpilot.com/v1/agents/2f7c1d4e-9b3a-4c6d-8e5f-0a1b2c3d4e5f/script" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The document.

ScriptDocumentResult

Field	Type	Always	Meaning
`agentId`	string (uuid)	yes
`version`	string	yes	The base version an apply must carry.
`script`	ScriptDocument	yes
`context`	ScriptContext	no

ScriptDocument

The agent's authored text. Every field is optional on write; only the fields given change.

Field	Type	Always	Meaning
`instructions`	string	no
`persona`	string	no
`behavior`	string	no
`welcomeMessage`	string	no
`chatPlaceholder`	string	no
`tone`	string	no
`skills`	array of string	no	Slugs the agent runs

ScriptContext

What an author needs before drafting.

Field	Type	Always	Meaning
`agent`	object	no
`skills`	array of object	no
`knowledgeBases`	array of object	no
`forms`	array of object	no
`offers`	array of object	no
`tours`	array of object	no
`activeScript`	object or null	no	The active agent script's prompts and modules, read-only here.

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 script edit

PUT /agents/{id}/script

Scope: agents:write. Operation id: applyAgentScript.

Writes the fields given when baseVersion matches the document's current version; otherwise 409 stale with currentVersion, and the caller re-reads. Lint errors (severity error) refuse the write with 400 lint-failed and the problems. Nothing is published.

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.
`id`	path	string	The agent's UUID or public id.

Example request

curl "https://api.showpilot.com/v1/agents/2f7c1d4e-9b3a-4c6d-8e5f-0a1b2c3d4e5f/script" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

The document as written and its new version.

Field	Type	Always
`agentId`	string (uuid)	yes
`version`	string	yes
`script`	ScriptDocument	yes
`problems`	array of LintProblem	yes

ScriptDocument

The agent's authored text. Every field is optional on write; only the fields given change.

Field	Type	Always	Meaning
`instructions`	string	no
`persona`	string	no
`behavior`	string	no
`welcomeMessage`	string	no
`chatPlaceholder`	string	no
`tone`	string	no
`skills`	array of string	no	Slugs the agent runs

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	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 script edit, writing nothing

POST /agents/{id}/script/propose

Scope: agents:read. Operation id: proposeAgentScript.

The compiler step for a harness. Returns a line diff per changed field, the lint problems, and whether an apply would be accepted.

Parameters

Name	In	Type	Meaning
`id`	path	string	The agent's UUID or public id.

Example request

curl "https://api.showpilot.com/v1/agents/2f7c1d4e-9b3a-4c6d-8e5f-0a1b2c3d4e5f/script/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`).
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.

Publish the agent's current draft as a new revision

POST /agents/{id}/publish

Scope: agents:write. Operation id: publishAgent.

The same write the dashboard's Publish button makes; visitors get the frozen revision from now on.

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.
`id`	path	string	The agent's UUID or public id.

Example request

curl "https://api.showpilot.com/v1/agents/2f7c1d4e-9b3a-4c6d-8e5f-0a1b2c3d4e5f/publish" \
  -H "Authorization: Bearer $SHOWPILOT_API_KEY"

Runs against your sandbox with a test key.

Response

Status 201.

The revision.

Field	Type	Always
`agentId`	string (uuid)	yes
`revisionId`	string (uuid)	yes
`publishedVersion`	integer	yes
`publishedAt`	string (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`.
409	The write cannot apply. Code `conflict` when the object's state refuses it (a follow-up already closed); code `idempotency-mismatch` when the `Idempotency-Key` was already used for a different request.
429	The key's bucket is empty. Code `rate-limited`; wait the `Retry-After` seconds.

On this page