DocsAPI reference

List widget designs

The preset picker's contents, and which of them this plan can use.

get/api/agents/widget/designs
Authentication
Bearer token
Retries
Safe to repeat
Body
None
Version
2026-09-03

Registered above /{agent_id} because FastAPI matches in declaration order and widget would otherwise be read as an agent id.

The locked ones are returned, not filtered out. A picker that hides what the plan does not include cannot sell it, and the whole commercial case for the premium half of this catalogue is that somebody looks at it. Each row carries its tier; required_plan says what the cheapest plan that unlocks them is, so the lock can name a price instead of saying no.

Responses#

  • 200OKapplication/json

    object

    5 response headers
    RateLimit-Limit

    Requests permitted in the current window.

    RateLimit-Remaining

    Requests left in the current window. Back off before it reaches 0.

    RateLimit-Reset

    Seconds until the current window resets.

    X-API-Version

    The dated version of the API contract that served this response, e.g. 2026-09-03. Pin against it; it changes only when a response shape changes incompatibly.

    X-Request-ID

    Quote this in a support request to identify the call.

Errors#

Failures use one envelope on every endpoint, described in Retries, versioning and limits. The codes you are most likely to meet here:

  • unauthenticated · 401 — The request carried no API key, or one the API could not verify.
  • forbidden · 403 — The key is valid, but it is not allowed to do this — either the scope is missing or the resource belongs to another workspace.
  • rate_limited · 429 — Too many requests in the current window. The limit is per workspace, and some endpoints add a per-agent limit on top.

More Agents endpoints#

Something unclear or missing? Tell us and we’ll fix it.