---
title: "API reference"
description: "Every endpoint of the moderation API in one table, the fraud prevention routes, and the OpenAPI document."
canonical_url: "https://www.openshield.dev/docs/api-reference"
---
# API reference

> Every endpoint of the moderation API in one table, the fraud prevention routes, and the OpenAPI document.

The base URL is `https://api.openshield.dev`. Every endpoint except the last two of the table needs an [API key](https://www.openshield.dev/docs/authentication). The fraud prevention API has [its own routes](#fraud-prevention-endpoints). The complete description, with every field, is the OpenAPI 3.1 document: [`/docs/api/openapi.json`](https://www.openshield.dev/docs/api/openapi.json).

## Endpoints

<table>
<thead>
  <tr>
    <th>
      Method and path
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        POST /v1/image
      </code>
    </td>
    
    <td>
      Checks an image sent as the raw body, or at a public <code>
        url
      </code>
      
      . See <a href="https://www.openshield.dev/docs/images">
        images
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /v1/text
      </code>
    </td>
    
    <td>
      Checks a text sent as JSON. See <a href="https://www.openshield.dev/docs/texts">
        texts
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /v1/workflows
      </code>
    </td>
    
    <td>
      Lists the names and current versions of the workflows the key may use. See <a href="https://www.openshield.dev/docs/workflows">
        workflows
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /1.0/check-workflow.json
      </code>
    </td>
    
    <td>
      Checks an image, SightEngine-compatible, as a multipart form. See <a href="https://www.openshield.dev/docs/migrating-from-sightengine">
        migrating from SightEngine
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /1.0/check-workflow.json
      </code>
    </td>
    
    <td>
      Checks an image by its <code>
        url
      </code>
      
      , SightEngine-compatible, with the key in the <code>
        Authorization
      </code>
      
       or <code>
        X-Api-Key
      </code>
      
       header.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /1.0/text/check-workflow.json
      </code>
    </td>
    
    <td>
      Checks a text, SightEngine-compatible, as a multipart form.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /health
      </code>
    </td>
    
    <td>
      <code>
        {"status": "ok"}
      </code>
      
       when the service is ready, <code>
        503
      </code>
      
       otherwise. No key.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /openapi.json
      </code>
    </td>
    
    <td>
      The OpenAPI document of the running version. No key.
    </td>
  </tr>
</tbody>
</table>

## 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](https://www.openshield.dev/docs/fraud-prevention) describes how to use it. The complete list, with its fields, is in the [OpenAPI document](https://www.openshield.dev/docs/api/openapi.json).

<table>
<thead>
  <tr>
    <th>
      Method and path
    </th>
    
    <th>
      What it does
    </th>
    
    <th>
      Scope
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        POST /fraud/v1/decide
      </code>
    </td>
    
    <td>
      Decides on an event before you act on it.
    </td>
    
    <td>
      <code>
        fraud_events
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /fraud/v1/events
      </code>
    </td>
    
    <td>
      Reports an event after the fact.
    </td>
    
    <td>
      <code>
        fraud_events
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /fraud/v1/events/batch
      </code>
    </td>
    
    <td>
      Reports up to 100 events at once.
    </td>
    
    <td>
      <code>
        fraud_events
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /fraud/v1/cases/{id}/appeal
      </code>
    </td>
    
    <td>
      Passes on an end user's appeal of a case.
    </td>
    
    <td>
      <code>
        fraud_events
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /fraud/v1/statements/{id}
      </code>
    </td>
    
    <td>
      Reads the statement of reasons of a decision.
    </td>
    
    <td>
      <code>
        fraud_events
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /fraud/v1/actors/{id}
      </code>
      
      , <code>
        /cluster
      </code>
    </td>
    
    <td>
      Reads an account, and the accounts linked to it.
    </td>
    
    <td>
      <code>
        fraud
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /fraud/v1/actors/{id}/label
      </code>
      
      , <code>
        /status
      </code>
      
      , <code>
        /snoozes
      </code>
    </td>
    
    <td>
      Labels an account, sets its status, silences a rule for it.
    </td>
    
    <td>
      <code>
        fraud
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DELETE /fraud/v1/actors/{id}/snoozes/{rule}
      </code>
    </td>
    
    <td>
      Lifts a snooze.
    </td>
    
    <td>
      <code>
        fraud
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /fraud/v1/tenants/{id}
      </code>
      
      , <code>
        POST .../status
      </code>
    </td>
    
    <td>
      Reads a workspace of your own users, and sets its status.
    </td>
    
    <td>
      <code>
        fraud
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /fraud/v1/cases
      </code>
      
      , <code>
        GET /fraud/v1/cases/{id}
      </code>
      
      , <code>
        POST /fraud/v1/cases/{id}/resolve
      </code>
    </td>
    
    <td>
      Lists, reads and resolves cases.
    </td>
    
    <td>
      <code>
        fraud
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /fraud/v1/subjects/{id}/export
      </code>
      
      , <code>
        DELETE /fraud/v1/subjects/{id}
      </code>
    </td>
    
    <td>
      Exports, or erases, what is kept about a person.
    </td>
    
    <td>
      <code>
        fraud
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /fraud/v1/lists
      </code>
      
      , <code>
        GET
      </code>
      
      , <code>
        POST
      </code>
      
       and <code>
        DELETE /fraud/v1/lists/{name}/items
      </code>
    </td>
    
    <td>
      Lists your lists and fills them.
    </td>
    
    <td>
      <code>
        fraud
      </code>
    </td>
  </tr>
</tbody>
</table>

Its errors are in [responses and errors](https://www.openshield.dev/docs/responses-and-errors), its prices in [limits and quotas](https://www.openshield.dev/docs/limits-and-quotas).

## Common to every endpoint

- **Authentication**: `Authorization: Bearer <key>` or `X-Api-Key: <key>`. The compatible endpoints take the key in the `api_secret` form field.
- **Server-side only**: a request that carries an `Origin` header is refused with `403 forbidden`.
- **Errors**: `{"status": "failure", "error": {"type", "code", "message"}}`. See [responses and errors](https://www.openshield.dev/docs/responses-and-errors) for every type.
- **Headers**: `X-Request-Id`, `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `X-Quota-Used`, `X-Quota-Limit`, and `Retry-After` when you must wait.
- **Limits**: see [limits and quotas](https://www.openshield.dev/docs/limits-and-quotas).

## The OpenAPI document

```bash
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.


## Sitemap

See the full [sitemap](https://www.openshield.dev/sitemap.md) for all pages.