Starts an asynchronous generation job for a URL and returns an id. You can then use the get-wrap endpoint to poll for the result.

Request

Send JSON with a required url field. Optionally include a webhook to be notified when the report is ready. Authenticate with an API key via the Authorization header.

curl -X POST /api/generate \
  -H "Authorization: Bearer $UNBUBBLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.theverge.com/2025/12/12/12345678/example-article"
  }'

With a webhook (optional)

curl -X POST /api/generate \
  -H "Authorization: Bearer $UNBUBBLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.theverge.com/2025/12/12/12345678/example-article",
    "webhook": {
      "url": "https://example.com/unbubble/webhooks",
      "secret": "whsec_your_webhook_secret"
    },
    "metadata": {
      "requestId": "req_123",
      "userId": "user_456"
    }
  }'

Response

The response body is a discriminated union keyed by ok and reason.

200 OK — started

{
  "ok": true,
  "id": "ubn_01HZYQ3P9J7P7V9Q2K4K6M9S9A"
}

401 Unauthorized — missing or invalid API key

{
  "ok": false,
  "reason": "unauthenticated",
  "error": "Missing or invalid API key"
}

400 Bad Request — invalid URL

{
  "ok": false,
  "reason": "invalid_url",
  "error": "Invalid URL"
}

429 Too Many Requests — daily limit reached

{
  "ok": false,
  "reason": "rate_limited",
  "error": "You have reached the daily limit"
}

500 Internal Server Error — generation failed

{
  "ok": false,
  "reason": "failed",
  "error": "Upstream generation failed",
  "id": "ubn_01HZYQ3P9J7P7V9Q2K4K6M9S9A"
}

Fetch the latest status for a wrap. If it's still generating, keep polling. If it's completed, the response includes the generated report.

Request

curl -X GET /api/get-wrap/ubn_01HZYQ3P9J7P7V9Q2K4K6M9S9A \
  -H "Authorization: Bearer $UNBUBBLE_API_KEY"

Response

200 OK — generating

{
  "ok": true,
  "wrap": {
    "id": "ubn_01HZYQ3P9J7P7V9Q2K4K6M9S9A",
    "status": "generating",
    "url": "https://www.theverge.com/2025/12/12/12345678/example-article",
    "createdAt": "2025-12-30T11:02:30.123Z"
  }
}

200 OK — completed

{
  "ok": true,
  "wrap": {
    "id": "ubn_01HZYQ3P9J7P7V9Q2K4K6M9S9A",
    "status": "completed",
    "url": "https://www.theverge.com/2025/12/12/12345678/example-article",
    "title": "Example article",
    "summary": "Short high-signal summary of what the article claims.",
    "keyFacts": [
      {
        "claim": "A specific claim from the article",
        "verdict": "uncertain",
        "evidence": ["Evidence item 1", "Evidence item 2"]
      },
      ...
    ],
    "context": ["Relevant context point 1", "Relevant context point 2"],
    "opinions": ["Viewpoint 1", "Viewpoint 2"]
  }
}

200 OK — failed

{
  "ok": true,
  "wrap": {
    "id": "ubn_01HZYQ3P9J7P7V9Q2K4K6M9S9A",
    "status": "failed",
    "error": "Upstream generation failed"
  }
}

404 Not Found — unknown id

{
  "ok": false,
  "reason": "not_found",
  "error": "Wrap not found"
}

If you include webhook.url when generating, Unbubble will send an HTTP POST to your endpoint on completion or failure. To verify authenticity, set webhook.secret and validate the HMAC signature.

Events

wrap.completed
wrap.failed

Headers

Unbubble-Event: wrap.completed
Unbubble-Id: evt_01HZYQ3P9J7P7V9Q2K4K6M9S9A
Unbubble-Signature: sha256=...

Payload (example)

{
  "event": "wrap.completed",
  "sentAt": "2025-12-30T11:04:10.456Z",
  "wrap": {
    "id": "ubn_01HZYQ3P9J7P7V9Q2K4K6M9S9A",
    "status": "completed",
    "url": "https://www.theverge.com/2025/12/12/12345678/example-article",
    "title": "Example article",
    "summary": "Short high-signal summary of what the article claims.",
    ...
  },
  "metadata": {
    "requestId": "req_123",
    "userId": "user_456"
  }
}

Signature: sha256=HMAC_SHA256(rawBody, webhook.secret). If your webhook returns a non-2xx response, Unbubble may retry with exponential backoff.