DevelopersReference
Offers
The authored plays the agent delivers — copy, chips, a call to action, who sees them and what converting means.
Base URL https://api.showpilot.com/v1. Every call needs Authorization: Bearer <api key>; see Authentication.
List offers
GET /offers
Scope: offers:read. Operation id: listOffers.
Every offer, newest edit first, with its lifetime shown and accepted counts.
Parameters
| Name | In | Type | Meaning |
|---|---|---|---|
active | query | boolean | Only live offers, or only retired ones. Absent returns both. |
Example request
curl "https://api.showpilot.com/v1/offers" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Runs against your sandbox with a test key.
Response
The offers.
| Field | Type | Always | Meaning |
|---|---|---|---|
items | array of Offer | yes |
Offer
| Field | Type | Always | Meaning |
|---|---|---|---|
id | string (uuid) | yes | |
name | string | yes | Internal name. Visitors never see it. |
format | toaster · in_chat | yes | |
goal | meeting_booked · lead_captured · content_viewed · engaged | yes | What counts as converting this play. |
isActive | boolean | yes | False retires the offer and keeps its history. There is no delete. |
headline | string or null | yes | |
message | string | yes | The copy the visitor reads. |
chips | array of string | yes | Quick replies. Two render. |
ctaLabel | string or null | yes | Button text. Null means no button. |
ctaAction | OfferCtaAction | yes | |
imageUrl | string or null | yes | |
mediaRefId | string or null (uuid) | yes | |
agentPersonalize | boolean | yes | Lets the agent rewrite the headline and body for the visitor in conversation. The design |
deploy | OfferDeploy | yes | |
design | object or null | yes | The creative as data — layout |
conversion | OfferConversion | yes | |
audienceIds | array of string (uuid) | yes | Audiences the agent may offer this to in conversation. Empty means any audience it matches. |
stats | object | yes | Lifetime counters from the selector. |
createdAt | string (date-time) | yes | |
updatedAt | string (date-time) | yes |
OfferCtaAction
What the button does. none is a chips-only prompt. open_experience launches a published guided experience; open_content opens one asset.
| Field | Type | Always | Meaning |
|---|---|---|---|
type | none · book_meeting · capture_lead · navigate · open_content · open_experience | yes | |
url | string | no | For navigate. |
contentRefId | string (uuid) | no | For open_content. |
experienceId | string (uuid) | no | For open_experience. |
OfferDeploy
The arrival gates. Present means the offer can present itself on the site; absent or null means the agent may still offer it in conversation but nothing shows on arrival. Every gate narrows: an absent gate matches everything. CRM and industry gates fail closed — an unresolved visitor never sees them.
| Field | Type | Always | Meaning |
|---|---|---|---|
live | boolean | yes | The master switch. False keeps the configuration and shows nothing. |
presentation | interstitial · toast · banner | yes | |
hosts | array of string | no | Site hostnames, e.g. "www.acme.com". Empty means every site you deploy on. |
includePages | array of string | no | Path patterns, e.g. "/pricing" or "/blog/*". Empty means all pages. |
excludePages | array of string | no | |
utm | object | no | Campaign arrival condition |
referrerHosts | array of string | no | Referrer hostnames, e.g. "linkedin.com". |
visitorType | new · returning | no | |
crm | object | no | Matched against the CRM you connected. Never presents to a visitor it cannot resolve. |
industries | array of string | no | Matched against the visitor's enriched account industry |
devices | array of desktop · mobile | no | |
afterSeconds | integer | no | Delay after page load. Absent is immediately. |
startsAt | string | no | Campaign start |
endsAt | string | no | Campaign end |
OfferConversion
What fulfilling the play collects, and where the conversion lands in your stack.
| Field | Type | Always | Meaning |
|---|---|---|---|
collect | array of email · name · phone · company | no | Fields the agent asks for. It skips anything it already knows about the visitor. |
formId | string (uuid) | no | An agent form to run instead of collect; its own after-steps then fire |
agentNote | string | no | What the agent should do once the visitor accepts. Joins the runtime prompt. |
destination | object | 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). |
| 429 | The key's bucket is empty. Code rate-limited; wait the Retry-After seconds. |
Create an offer
POST /offers
Scope: offers:write. Operation id: createOffer.
Requires Idempotency-Key. A new offer is active immediately for the agent to use in conversation. It does not present itself on the site until you send a deploy with live: true.
Example request
curl "https://api.showpilot.com/v1/offers" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Runs against your sandbox with a test key.
Response
Status 201.
The offer.
Offer
| Field | Type | Always | Meaning |
|---|---|---|---|
id | string (uuid) | yes | |
name | string | yes | Internal name. Visitors never see it. |
format | toaster · in_chat | yes | |
goal | meeting_booked · lead_captured · content_viewed · engaged | yes | What counts as converting this play. |
isActive | boolean | yes | False retires the offer and keeps its history. There is no delete. |
headline | string or null | yes | |
message | string | yes | The copy the visitor reads. |
chips | array of string | yes | Quick replies. Two render. |
ctaLabel | string or null | yes | Button text. Null means no button. |
ctaAction | OfferCtaAction | yes | |
imageUrl | string or null | yes | |
mediaRefId | string or null (uuid) | yes | |
agentPersonalize | boolean | yes | Lets the agent rewrite the headline and body for the visitor in conversation. The design |
deploy | OfferDeploy | yes | |
design | object or null | yes | The creative as data — layout |
conversion | OfferConversion | yes | |
audienceIds | array of string (uuid) | yes | Audiences the agent may offer this to in conversation. Empty means any audience it matches. |
stats | object | yes | Lifetime counters from the selector. |
createdAt | string (date-time) | yes | |
updatedAt | string (date-time) | yes |
OfferCtaAction
What the button does. none is a chips-only prompt. open_experience launches a published guided experience; open_content opens one asset.
| Field | Type | Always | Meaning |
|---|---|---|---|
type | none · book_meeting · capture_lead · navigate · open_content · open_experience | yes | |
url | string | no | For navigate. |
contentRefId | string (uuid) | no | For open_content. |
experienceId | string (uuid) | no | For open_experience. |
OfferDeploy
The arrival gates. Present means the offer can present itself on the site; absent or null means the agent may still offer it in conversation but nothing shows on arrival. Every gate narrows: an absent gate matches everything. CRM and industry gates fail closed — an unresolved visitor never sees them.
| Field | Type | Always | Meaning |
|---|---|---|---|
live | boolean | yes | The master switch. False keeps the configuration and shows nothing. |
presentation | interstitial · toast · banner | yes | |
hosts | array of string | no | Site hostnames, e.g. "www.acme.com". Empty means every site you deploy on. |
includePages | array of string | no | Path patterns, e.g. "/pricing" or "/blog/*". Empty means all pages. |
excludePages | array of string | no | |
utm | object | no | Campaign arrival condition |
referrerHosts | array of string | no | Referrer hostnames, e.g. "linkedin.com". |
visitorType | new · returning | no | |
crm | object | no | Matched against the CRM you connected. Never presents to a visitor it cannot resolve. |
industries | array of string | no | Matched against the visitor's enriched account industry |
devices | array of desktop · mobile | no | |
afterSeconds | integer | no | Delay after page load. Absent is immediately. |
startsAt | string | no | Campaign start |
endsAt | string | no | Campaign end |
OfferConversion
What fulfilling the play collects, and where the conversion lands in your stack.
| Field | Type | Always | Meaning |
|---|---|---|---|
collect | array of email · name · phone · company | no | Fields the agent asks for. It skips anything it already knows about the visitor. |
formId | string (uuid) | no | An agent form to run instead of collect; its own after-steps then fire |
agentNote | string | no | What the agent should do once the visitor accepts. Joins the runtime prompt. |
destination | object | 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). |
| 429 | The key's bucket is empty. Code rate-limited; wait the Retry-After seconds. |
Read an offer
GET /offers/{id}
Scope: offers:read. Operation id: getOffer.
Parameters
| Name | In | Type | Meaning |
|---|---|---|---|
id | path | string (uuid) | The offer's UUID. |
Example request
curl "https://api.showpilot.com/v1/offers/<id>" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Runs against your sandbox with a test key.
Response
The offer.
Offer
| Field | Type | Always | Meaning |
|---|---|---|---|
id | string (uuid) | yes | |
name | string | yes | Internal name. Visitors never see it. |
format | toaster · in_chat | yes | |
goal | meeting_booked · lead_captured · content_viewed · engaged | yes | What counts as converting this play. |
isActive | boolean | yes | False retires the offer and keeps its history. There is no delete. |
headline | string or null | yes | |
message | string | yes | The copy the visitor reads. |
chips | array of string | yes | Quick replies. Two render. |
ctaLabel | string or null | yes | Button text. Null means no button. |
ctaAction | OfferCtaAction | yes | |
imageUrl | string or null | yes | |
mediaRefId | string or null (uuid) | yes | |
agentPersonalize | boolean | yes | Lets the agent rewrite the headline and body for the visitor in conversation. The design |
deploy | OfferDeploy | yes | |
design | object or null | yes | The creative as data — layout |
conversion | OfferConversion | yes | |
audienceIds | array of string (uuid) | yes | Audiences the agent may offer this to in conversation. Empty means any audience it matches. |
stats | object | yes | Lifetime counters from the selector. |
createdAt | string (date-time) | yes | |
updatedAt | string (date-time) | yes |
OfferCtaAction
What the button does. none is a chips-only prompt. open_experience launches a published guided experience; open_content opens one asset.
| Field | Type | Always | Meaning |
|---|---|---|---|
type | none · book_meeting · capture_lead · navigate · open_content · open_experience | yes | |
url | string | no | For navigate. |
contentRefId | string (uuid) | no | For open_content. |
experienceId | string (uuid) | no | For open_experience. |
OfferDeploy
The arrival gates. Present means the offer can present itself on the site; absent or null means the agent may still offer it in conversation but nothing shows on arrival. Every gate narrows: an absent gate matches everything. CRM and industry gates fail closed — an unresolved visitor never sees them.
| Field | Type | Always | Meaning |
|---|---|---|---|
live | boolean | yes | The master switch. False keeps the configuration and shows nothing. |
presentation | interstitial · toast · banner | yes | |
hosts | array of string | no | Site hostnames, e.g. "www.acme.com". Empty means every site you deploy on. |
includePages | array of string | no | Path patterns, e.g. "/pricing" or "/blog/*". Empty means all pages. |
excludePages | array of string | no | |
utm | object | no | Campaign arrival condition |
referrerHosts | array of string | no | Referrer hostnames, e.g. "linkedin.com". |
visitorType | new · returning | no | |
crm | object | no | Matched against the CRM you connected. Never presents to a visitor it cannot resolve. |
industries | array of string | no | Matched against the visitor's enriched account industry |
devices | array of desktop · mobile | no | |
afterSeconds | integer | no | Delay after page load. Absent is immediately. |
startsAt | string | no | Campaign start |
endsAt | string | no | Campaign end |
OfferConversion
What fulfilling the play collects, and where the conversion lands in your stack.
| Field | Type | Always | Meaning |
|---|---|---|---|
collect | array of email · name · phone · company | no | Fields the agent asks for. It skips anything it already knows about the visitor. |
formId | string (uuid) | no | An agent form to run instead of collect; its own after-steps then fire |
agentNote | string | no | What the agent should do once the visitor accepts. Joins the runtime prompt. |
destination | object | 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. |
Change an offer
PATCH /offers/{id}
Scope: offers:write. Operation id: updateOffer.
Requires Idempotency-Key. Send only the fields that change. Changes take effect on the next visitor; nothing needs publishing. Set isActive: false to retire an offer — there is no delete, because an offer carries its own lifetime counters.
Parameters
| Name | In | Type | Meaning |
|---|---|---|---|
id | path | string (uuid) | The offer's UUID. |
Example request
curl "https://api.showpilot.com/v1/offers/<id>" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Runs against your sandbox with a test key.
Response
The updated offer.
Offer
| Field | Type | Always | Meaning |
|---|---|---|---|
id | string (uuid) | yes | |
name | string | yes | Internal name. Visitors never see it. |
format | toaster · in_chat | yes | |
goal | meeting_booked · lead_captured · content_viewed · engaged | yes | What counts as converting this play. |
isActive | boolean | yes | False retires the offer and keeps its history. There is no delete. |
headline | string or null | yes | |
message | string | yes | The copy the visitor reads. |
chips | array of string | yes | Quick replies. Two render. |
ctaLabel | string or null | yes | Button text. Null means no button. |
ctaAction | OfferCtaAction | yes | |
imageUrl | string or null | yes | |
mediaRefId | string or null (uuid) | yes | |
agentPersonalize | boolean | yes | Lets the agent rewrite the headline and body for the visitor in conversation. The design |
deploy | OfferDeploy | yes | |
design | object or null | yes | The creative as data — layout |
conversion | OfferConversion | yes | |
audienceIds | array of string (uuid) | yes | Audiences the agent may offer this to in conversation. Empty means any audience it matches. |
stats | object | yes | Lifetime counters from the selector. |
createdAt | string (date-time) | yes | |
updatedAt | string (date-time) | yes |
OfferCtaAction
What the button does. none is a chips-only prompt. open_experience launches a published guided experience; open_content opens one asset.
| Field | Type | Always | Meaning |
|---|---|---|---|
type | none · book_meeting · capture_lead · navigate · open_content · open_experience | yes | |
url | string | no | For navigate. |
contentRefId | string (uuid) | no | For open_content. |
experienceId | string (uuid) | no | For open_experience. |
OfferDeploy
The arrival gates. Present means the offer can present itself on the site; absent or null means the agent may still offer it in conversation but nothing shows on arrival. Every gate narrows: an absent gate matches everything. CRM and industry gates fail closed — an unresolved visitor never sees them.
| Field | Type | Always | Meaning |
|---|---|---|---|
live | boolean | yes | The master switch. False keeps the configuration and shows nothing. |
presentation | interstitial · toast · banner | yes | |
hosts | array of string | no | Site hostnames, e.g. "www.acme.com". Empty means every site you deploy on. |
includePages | array of string | no | Path patterns, e.g. "/pricing" or "/blog/*". Empty means all pages. |
excludePages | array of string | no | |
utm | object | no | Campaign arrival condition |
referrerHosts | array of string | no | Referrer hostnames, e.g. "linkedin.com". |
visitorType | new · returning | no | |
crm | object | no | Matched against the CRM you connected. Never presents to a visitor it cannot resolve. |
industries | array of string | no | Matched against the visitor's enriched account industry |
devices | array of desktop · mobile | no | |
afterSeconds | integer | no | Delay after page load. Absent is immediately. |
startsAt | string | no | Campaign start |
endsAt | string | no | Campaign end |
OfferConversion
What fulfilling the play collects, and where the conversion lands in your stack.
| Field | Type | Always | Meaning |
|---|---|---|---|
collect | array of email · name · phone · company | no | Fields the agent asks for. It skips anything it already knows about the visitor. |
formId | string (uuid) | no | An agent form to run instead of collect; its own after-steps then fire |
agentNote | string | no | What the agent should do once the visitor accepts. Joins the runtime prompt. |
destination | object | 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. |
| 429 | The key's bucket is empty. Code rate-limited; wait the Retry-After seconds. |