API endpoints

All paths are relative to https://openbait.com/api/v1/ext. Every request needs Authorization: Bearer <key> (Authentication).

The Case object

Every endpoint returns cases in this shape.

{
  "id": "d3a9m7f05n8u7r1m4r20",
  "url": "https://example-copy.shop/checkout",
  "domain": "example-copy.shop",
  "status": "opened",
  "createdAt": "2026-10-22T12:00:00Z",
  "updatedAt": "2026-10-22T12:05:00Z",
  "offlineAt": null,
  "consoleUrl": "https://openbait.com/console/takedown/d3a9m7f05n8u7r1m4r20",
  "blocklistOnly": false
}

Case statuses

A case usually moves opened → blocked → down → resolved, but it can skip steps. Only domain-removed is final: a site resolved after a week offline that comes back online becomes re-emerged; a closed case stays resolved. New statuses may be added in /v1, so handle an unknown value as "still in progress".

Open a case

POST /cases

Opens a takedown case for a URL, the same as reporting a fake site in the console and confirming it. A new case uses one of the month's takedowns.

Request headers

Request body

The URL must be a public website. These are refused with 400 invalid_request, and the message says which:

curl -X POST https://openbait.com/api/v1/ext/cases \
  -H "Authorization: Bearer $OPENBAIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-4521" \
  -d '{"url": "https://example-copy.shop/checkout", "note": "Ticket 4521"}'

Responses

A 201 or 200 case with blocklistOnly: true was added to the browser warning lists only and used none of the month's takedowns (for example, an open case the console opened after the takedowns ran out).

Any endpoint can also answer 401, 403, 413, 429 or 500, and 404 not_found for an unknown path or 405 invalid_request for a method a path doesn't take. A request that takes longer than 30 seconds can get 504 Gateway Timeout without a JSON body, so check the status code and Content-Type before you parse the body. See Errors.

Idempotency

Send an Idempotency-Key so that a retry after a timeout can't open a second case.

• The key is remembered for 24 hours, per organization.
• Same key and same body: you get the first response again, with the same status code and an Idempotent-Replayed: true header. Nothing new happens.
• While the first request with a key is still being processed, another request with the same key gets 409 idempotency_conflict (message: a request with this Idempotency-Key is still being processed). Wait a few seconds and retry with the same key.
• Same key and a different body: 409 idempotency_conflict (message: this Idempotency-Key was used with a different request body). Use a new key only for a new request.
• A 5xx response is not kept: a retry with the same key is processed again.
• Use something unique to the request, such as your ticket ID or a UUID.

Even without the header, sending the same URL twice doesn't use two takedowns: the second call returns 200 with the open case.

Get a case

GET /cases/{id}

curl https://openbait.com/api/v1/ext/cases/d3a9m7f05n8u7r1m4r20 \
  -H "Authorization: Bearer $OPENBAIT_API_KEY"

List cases

GET /cases?status=&limit=&cursor=

Newest first.

curl "https://openbait.com/api/v1/ext/cases?status=down&limit=50" \
  -H "Authorization: Bearer $OPENBAIT_API_KEY"

{
  "data": [
    {
      "id": "d3a9m7f05n8u7r1m4r20",
      "url": "https://example-copy.shop/checkout",
      "domain": "example-copy.shop",
      "status": "down",
      "createdAt": "2026-10-22T12:00:00Z",
      "updatedAt": "2026-10-23T08:40:00Z",
      "offlineAt": "2026-10-23T08:40:00Z",
      "consoleUrl": "https://openbait.com/console/takedown/d3a9m7f05n8u7r1m4r20",
      "blocklistOnly": false
    }
  ],
  "nextCursor": "eyJ0IjoiMjAyNi0xMC0yMlQxMjowMDowMFoifQ"
}

The cursor is opaque: don't build or change one yourself. To poll for changes, a webhook is better than listing over and over.