Actions
What a link, a button or a campaign arrival starts the agent on. Live on save, no publish needed.
Base URL https://api.showpilot.com/v1. Every call needs Authorization: Bearer <api key>; see Authentication.
The agent's Actions
GET /agents/{id}/actions
Scope: agents:read. Operation id: listActions.
Every Action on the agent, with how many times each fired in the
last 7 days and its link. An Action opens the agent on a task you
set; a click on the link, a data-showpilot-action button, or an
arrival rule starts it. Read from the agent row: live on save.
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/actions" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Response
The Actions, in the operator's order (arrival rules match in this order).
| Field | Type | Always | Meaning |
|---|---|---|---|
items | array of object | yes |
Action
| Field | Type | Always | Meaning |
|---|---|---|---|
id | string | yes | What the page uses: data-showpilot-action, #action=. |
name | string | yes | |
task | string | yes | |
opens | ActionOpens | yes | |
destination | string or null (uri) | yes | |
campaignContext | string or null | yes | |
enabled | boolean | yes | |
arrival | object | yes | |
link | string | yes | The link as the dashboard shows it: <destination>#action=<id>, or #action=<id> without a destination. |
ActionOpens
What the agent opens as its first move. tour, experience, form and link carry their id or URL.
| Field | Type | Always | Meaning |
|---|---|---|---|
kind | conversation · meeting · content · tour · experience · link · form | yes | |
tourPublicId | string | no | |
experienceId | string | no | |
formId | string | no | |
url | string (uri) | no |
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. |
Create or replace an Action
PUT /agents/{id}/actions/{actionId}
Scope: agents:write. Operation id: putAction.
Creates the Action when the id is free (201), replaces it when it
exists (200). The same validator as the dashboard form: the task is
required, a form or tour target needs its id, a destination must be
a full URL. Live as soon as it is saved. Requires Idempotency-Key.
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. |
actionId | path | string | The Action's id, as the page will use it: letters, numbers, dashes or underscores, up to 64. |
Example request
curl "https://api.showpilot.com/v1/agents/2f7c1d4e-9b3a-4c6d-8e5f-0a1b2c3d4e5f/actions/request-a-quote" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Response
The Action, replaced.
Every field of Action, plus:
| Field | Type | Always | Meaning |
|---|---|---|---|
created | boolean | yes |
Action
| Field | Type | Always | Meaning |
|---|---|---|---|
id | string | yes | What the page uses: data-showpilot-action, #action=. |
name | string | yes | |
task | string | yes | |
opens | ActionOpens | yes | |
destination | string or null (uri) | yes | |
campaignContext | string or null | yes | |
enabled | boolean | yes | |
arrival | object | yes | |
link | string | yes | The link as the dashboard shows it: <destination>#action=<id>, or #action=<id> without a destination. |
ActionOpens
What the agent opens as its first move. tour, experience, form and link carry their id or URL.
| Field | Type | Always | Meaning |
|---|---|---|---|
kind | conversation · meeting · content · tour · experience · link · form | yes | |
tourPublicId | string | no | |
experienceId | string | no | |
formId | string | no | |
url | string (uri) | no |
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. |
| 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. |
Remove an Action
DELETE /agents/{id}/actions/{actionId}
Scope: agents:write. Operation id: deleteAction.
Removes the Action. Links and buttons that still name it open the agent plainly. Requires Idempotency-Key.
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 | |
actionId | path | string |
Example request
curl "https://api.showpilot.com/v1/agents/2f7c1d4e-9b3a-4c6d-8e5f-0a1b2c3d4e5f/actions/request-a-quote" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Response
Status 204. Removed.
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. |
Mint the link for an Action
GET /agents/{id}/actions/{actionId}/link
Scope: agents:read. Operation id: getActionLink.
The URL to put in an email, an ad or a CRM sequence. With a
destination (yours here, else the Action's) it is a full URL
carrying the utm tags and #action=<id>; without one it is the
bare #action=<id>, which works on any page the agent is deployed
on. Utm tags need a destination to ride on.
Parameters
| Name | In | Type | Meaning |
|---|---|---|---|
id | path | string | |
actionId | path | string | |
destination | query | string (uri) | A full page URL on the site the agent runs on. Overrides the Action's own destination. |
utm_source | query | string | |
utm_medium | query | string | |
utm_campaign | query | string | |
utm_term | query | string |
Example request
curl "https://api.showpilot.com/v1/agents/2f7c1d4e-9b3a-4c6d-8e5f-0a1b2c3d4e5f/actions/request-a-quote/link?destination=https://acme.com/pricing&utm_source=newsletter&utm_medium=email&utm_campaign=q4-launch" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Response
The link.
| Field | Type | Always | Meaning |
|---|---|---|---|
actionId | string | yes | |
url | string | 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. |