Create a widget
Creates one widget. Send an Idempotency-Key header with a unique value per logical operation, so that a retried request returns the original widget instead of creating a second one.
POST/widgets
Retry safely
Send an Idempotency-Key header with a value that is unique for each logical
operation. If the request times out and you retry it with the same key, this
example API returns the widget it already created. Without a key, a retry
creates a second widget.
curl -X POST https://api.example.com/v1/widgets \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: 8f14e45f-ea0b-4e1b-9b8a-2f7c1d3e5a90" \
-H "Content-Type: application/json" \
-d '{"name":"Checkout banner","status":"active","tags":["marketing"]}'Generate the key from the operation, not from the attempt. A new key on each retry defeats the mechanism, because the API cannot tell the two requests apart.
After it is created
A widget starts as a draft unless you set status to active. Only an
active widget is served to callers, so a draft is safe to create early and
finish later.
Authorizations
Authorizationbearerin headerrequiredBody
application/jsonrequirednamestringrequiredlength: 2–80 charsShown wherever the widget is listed.
descriptionstringlength: ≤ 500 charsWhat the widget is for. Write the removal condition here too.
statusenum<string>default: draftone of: draft, activeA widget starts as a draft unless you set this to active.
tagsstring[]Free-form labels. Use them to group widgets in a list.
Response
The widget was created.
idstringrequiredUnique and immutable.
namestringrequireddescriptionstringstatusenum<string>requiredone of: draft, active, archivedA widget is only served to callers while it is active.
tagsstring[]created_atstring<date-time>requiredRFC 3339, always UTC.
The API key is missing, malformed or revoked.
errorobjectrequiredA field failed validation. error.field names it.
errorobjectrequired