Widgets

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

Request

curl --request POST \
  --url 'https://api.example.com/v1/widgets' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Checkout banner"
}'

import json
import requests

url = "https://api.example.com/v1/widgets"
headers = {
  "Authorization": "<api-key>",
  "Content-Type": "application/json"
}
payload = json.loads("{\"name\":\"Checkout banner\"}")

response = requests.request("POST", url, headers=headers, json=payload)
print(response.json())

const response = await fetch("https://api.example.com/v1/widgets", {
  method: "POST",
  headers: {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "name": "Checkout banner"
  }),
});

const data = await response.json();
console.log(data);

<?php
$client = curl_init();

curl_setopt($client, CURLOPT_URL, "https://api.example.com/v1/widgets");
curl_setopt($client, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($client, CURLOPT_HTTPHEADER, [
    "Authorization: <api-key>",
    "Content-Type: application/json",
]);
curl_setopt($client, CURLOPT_POSTFIELDS, "{\"name\":\"Checkout banner\"}");
curl_setopt($client, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($client);
curl_close($client);
echo $response;

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("POST", "https://api.example.com/v1/widgets", bytes.NewBuffer([]byte("{\"name\":\"Checkout banner\"}")))
  req.Header.Set("Authorization", "<api-key>")
  req.Header.Set("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  data, _ := io.ReadAll(res.Body)
  fmt.Println(string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var request = HttpRequest.newBuilder(URI.create("https://api.example.com/v1/widgets"))
    .header("Authorization", "<api-key>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"name\":\"Checkout banner\"}"))
    .build();

var response = HttpClient.newHttpClient().send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

require 'net/http'
require 'json'

uri = URI("https://api.example.com/v1/widgets")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "<api-key>"
request["Content-Type"] = "application/json"
request.body = "{\"name\":\"Checkout banner\"}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts response.body

application/json

{
  "id": "wid_01HQ8ZK7",
  "name": "Checkout banner",
  "description": "Shown above the payment step.",
  "status": "active",
  "tags": [
    "marketing"
  ],
  "created_at": "2026-08-01T09:24:11Z"
}

{
  "error": {
    "code": "widget_not_found",
    "message": "No widget with this id exists.",
    "field": "name"
  }
}

{
  "error": {
    "code": "widget_not_found",
    "message": "No widget with this id exists.",
    "field": "name"
  }
}

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.

Terminalcurl -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.

{ "id": "wid_01HQ8ZK7", "name": "Checkout banner", "description": "Shown above the payment step.", "status": "active", "tags": [ "marketing" ], "created_at": "2026-08-01T09:24:11Z" }

Create a widget

Retry safely

After it is created

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown