API reference
The base URL is https://api.openshield.dev. Every endpoint except the last two of the table needs an API key. The fraud prevention API has its own routes. The complete description, with every field, is the OpenAPI 3.1 document: /docs/api/openapi.json.
Endpoints
| Method and path | What it does |
|---|---|
POST /v1/image | Checks an image sent as the raw body, or at a public url. See images. |
POST /v1/text | Checks a text sent as JSON. See texts. |
GET /v1/workflows | Lists the names and current versions of the workflows the key may use. See workflows. |
POST /1.0/check-workflow.json | Checks an image, SightEngine-compatible, as a multipart form. See migrating from SightEngine. |
GET /1.0/check-workflow.json | Checks an image by its url, SightEngine-compatible, with the key in the api_secret query parameter. |
POST /1.0/text/check-workflow.json | Checks a text, SightEngine-compatible, as a multipart form. |
GET /health | {"status": "ok"} when the service is ready, 503 otherwise. No key. |
GET /openapi.json | The OpenAPI document of the running version. No key. |
Fraud prevention endpoints
The fraud prevention API runs under /fraud/v1, with the same base URL and keys that carry fraud access: fraud_events for the reporting routes, fraud for all of them. Fraud prevention describes how to use it. The complete list, with its fields, is in the OpenAPI document.
| Method and path | What it does | Scope |
|---|---|---|
POST /fraud/v1/decide | Decides on an event before you act on it. | fraud_events |
POST /fraud/v1/events | Reports an event after the fact. | fraud_events |
POST /fraud/v1/events/batch | Reports up to 100 events at once. | fraud_events |
POST /fraud/v1/cases/{id}/appeal | Passes on an end user's appeal of a case. | fraud_events |
GET /fraud/v1/statements/{id} | Reads the statement of reasons of a decision. | fraud_events |
GET /fraud/v1/actors/{id}, /cluster | Reads an account, and the accounts linked to it. | fraud |
POST /fraud/v1/actors/{id}/label, /status, /snoozes | Labels an account, sets its status, silences a rule for it. | fraud |
DELETE /fraud/v1/actors/{id}/snoozes/{rule} | Lifts a snooze. | fraud |
GET /fraud/v1/tenants/{id}, POST .../status | Reads a workspace of your own users, and sets its status. | fraud |
GET /fraud/v1/cases, GET /fraud/v1/cases/{id}, POST /fraud/v1/cases/{id}/resolve | Lists, reads and resolves cases. | fraud |
GET /fraud/v1/subjects/{id}/export, DELETE /fraud/v1/subjects/{id} | Exports, or erases, what is kept about a person. | fraud |
GET /fraud/v1/lists, GET, POST and DELETE /fraud/v1/lists/{name}/items | Lists your lists and fills them. | fraud |
Its errors are in responses and errors, its prices in limits and quotas.
Common to every endpoint
- Authentication:
Authorization: Bearer <key>orX-Api-Key: <key>. The compatible endpoints take the key in theapi_secretform field. - Server-side only: a request that carries an
Originheader is refused with403 forbidden. - Errors:
{"status": "failure", "error": {"type", "code", "message"}}. See responses and errors for every type. - Headers:
X-Request-Id,RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset,X-Quota-Used,X-Quota-Limit, andRetry-Afterwhen you must wait. - Limits: see limits and quotas.
The OpenAPI document
curl https://api.openshield.dev/openapi.json
Use it to generate a client, to import the API into a tool such as Postman or Insomnia, or to give an AI agent the exact contract. The copy under /docs/api/openapi.json is published with each release of these docs.