> ## Documentation Index
> Fetch the complete documentation index at: https://developer.beeble.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> This site documents two API families. Choose the family before generating integration code and keep its request fields, billing, statuses, responses, and webhooks together.
> SwitchX API: POST /v1/switchx/generations; use /quickstart and /authentication. Completed generation files are under output.
> Enterprise API: POST /v1/products/{product}/jobs and GET /v1/product-jobs/{job_id}; use /enterprise/quickstart and /products. Check /enterprise for current access requirements. Completed product files are under outputs.
> For product jobs, fetch model-specific input_schema from GET /v1/products/{product}/models. OpenAPI defines the common job response; product guides show illustrative completed outputs. Do not treat output examples as exhaustive schemas.
> SwitchX 2.0 Finish uses the separate switchx_finish product and model_id switchx-2.0. Follow /products/switchx-finish: pass inputs.parent_job_id (a completed Standard switchx product generation's public dap_ ID owned by the same key owner, organization, and team) and inputs.target_resolution (1080 or 2160), without uploading media. Fast results, Finish results, and legacy SwitchX API generations cannot be parents. Estimate the transition, then submit and poll the new child ID; result files are under outputs.
> For product APIs, authenticate with an Organization API Key in x-api-key and keep the same organization and X-Beeble-Team-Id context for uploads, estimates, submissions, and reads. Use Beeble Cloud credits; product routes do not support USD.
> Follow /enterprise/llms-txt for the product API workflow: discover products and models, upload media, estimate credits, submit with an idempotency_key, and poll or receive webhooks. On an uncertain submission, retry the same body and key; do not create a replacement job.
> Product-job success is status=success; stop polling on failed, cancelled, or credit_required. Use the chosen product guide for completed response examples and download fields. Refer to /enterprise/errors, /enterprise/rate-limits, /guides/billing, and /guides/jobs for failures, limits, and refunds.

# Webhooks

> Receive job completion callbacks and handle duplicate deliveries.

## Using Webhooks

Set `callback_url` at the top level of a submission request. Use a public HTTPS
endpoint that accepts JSON POST requests.

```json theme={null}
{
  "callback_url": "https://your-server.example/beeble/webhook"
}
```

Add this field to your job request.

## Product job callbacks

`data` contains the job result. This example shows a failed job:

```json theme={null}
{
  "event_id": "dap_example",
  "type": "product.job.completed",
  "data": {
    "id": "dap_example",
    "product": "switchx",
    "model_id": "switchx-2.0",
    "organization_id": "org_example",
    "team_id": null,
    "billing_unit": "credits",
    "status": "failed",
    "progress": null,
    "credits_charged": null,
    "refunded": null,
    "outputs": {},
    "error": null,
    "created_at": "2026-09-15T00:00:00Z"
  }
}
```

Check `data.status`: the event name indicates the job finished, not that it
succeeded. Only `success` includes output files.

Delivery may repeat. Retryable failures get up to ten attempts; permanent failures
stop immediately. Redirects are not followed. Revoking the key or removing its
organization/team access stops delivery.

## Handling Webhooks

* Persist the event and return a successful `2xx` response within 10 seconds. Do longer work asynchronously.
* Deduplicate by `event_id`, which is the public job ID.
* Validate the payload and confirm the job using your authenticated Beeble API
  connection before taking sensitive actions. A received JSON body alone is not
  proof of its sender.
* Do not interpret a failed job or failure callback as confirmation of a refund.
  Read the fields described in [Billing & credits](/docs/guides/billing#charges-and-refunds).