# API Reference

> Source: https://pixelsystems.com/docs/api


Submit a file, read the verdict, and browse previous submissions.

The Pixel Systems API is organized around REST: predictable resource-oriented URLs, file uploads as [`multipart/form-data`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods/POST), JSON responses, and standard HTTP response codes and verbs. Every request authenticates with an API key; see [Authentication](https://pixelsystems.com/docs/api/authentication).

## Base URL

```text
https://api.pixelsystems.com
```

Every endpoint lives under `/v1`. A change that breaks an existing call arrives as a new API version, not as a change to `/v1`.

## Client libraries

Call the API over HTTP from any language, or generate a typed client from the API's [OpenAPI](https://www.openapis.org/) spec:

```text
https://api.pixelsystems.com/openapi.json
```

TypeScript [SDKs](https://pixelsystems.com/docs/sdk) are available on request.

## Workflow

The fastest way to verify a file, or up to 20 files of one case, is one call to [Assess a file](https://pixelsystems.com/docs/api/assess) (`/v1/assess`): upload the files as `multipart/form-data`, one `file` part each. The call waits for analysis by default and responds `200` with the finished job (status `completed` or `error`) when analysis ends inside the wait window; otherwise it returns `202` with a `processing` status and you poll the job until it finishes.

To read a result later, call [Get a job's result](https://pixelsystems.com/docs/api/get-job) (`/v1/jobs/{jobId}`) and poll until the job's `status` leaves `processing`. It ends as `completed` (with a `verdict` on each entry of `results[]`) or `error`. A job stays in `processing` until analysis finishes, which takes longer when the platform is busy. Each [pipeline](https://pixelsystems.com/docs/concepts#pipeline) sets a total time its jobs may wait for capacity. A job that reaches it ends as `error` rather than staying in `processing`, so every job reaches `completed` or `error`. Keep polling rather than resubmitting the file: a resubmission creates a second job, and the first one still completes. Pass `?wait=true` to long-poll instead of tight-looping. Use [List jobs](https://pixelsystems.com/docs/api/list-jobs) (`/v1/jobs`) to browse previous submissions.

## Example request

Send the files with your API key, one `file` part each:

```bash
curl -X POST "https://api.pixelsystems.com/v1/assess" \
  -H "Authorization: Bearer {api_key}" \
  -H "Idempotency-Key: case-123-photos" \
  -F "file=@front.jpg;type=image/jpeg" \
  -F "file=@side.jpg;type=image/jpeg" \
  -F 'metadata={"customer_case_id":"case-123"}'
```

## Example response

When analysis finishes inside the wait window, the call responds `200` with the completed job:

```json
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "results": [
    {
      "file": {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "name": "front.jpg",
        "size": 1834211,
        "type": "image/jpeg"
      },
      "status": "completed",
      "startedAt": "2026-06-01T12:00:01Z",
      "completedAt": "2026-06-01T12:00:14Z",
      "verdict": { "assessment": "ai_generated", "confidence": "high" },
      "dimensions": [
        {
          "key": "ai_detection",
          "assessment": "likely_ai",
          "score": 0.82,
          "confidence": "high"
        }
      ]
    },
    {
      "file": {
        "id": "9b2d3f41-6a8e-4c1b-9f0d-2e7a5c8b1d34",
        "name": "side.jpg",
        "size": 1650372,
        "type": "image/jpeg"
      },
      "status": "completed",
      "startedAt": "2026-06-01T12:00:01Z",
      "completedAt": "2026-06-01T12:00:12Z",
      "verdict": { "assessment": "authentic", "confidence": "medium" },
      "dimensions": [
        {
          "key": "ai_detection",
          "assessment": "likely_authentic",
          "score": 0.12,
          "confidence": "medium"
        }
      ]
    }
  ],
  "metadata": { "customer_case_id": "case-123" },
  "createdAt": "2026-06-01T12:00:00Z",
  "completedAt": "2026-06-01T12:00:14Z"
}
```

The job's result is `results[]`, one entry per file. Each completed entry carries a `verdict` (the assessment and a confidence level) and `dimensions`: one entry per axis of analysis with its `key`, `score`, and, where the analysis found some, structured evidence under `data`. The API returns keys and values, not display text, so your integration renders its own words from them. Field-by-field documentation lives in [`FileResult`](https://pixelsystems.com/docs/api/resources#fileresult); the reference page for [Get a job's result](https://pixelsystems.com/docs/api/get-job) shows an example of every response state.

## Explore the reference

- [Authentication](https://pixelsystems.com/docs/api/authentication): API keys and the `Authorization` header.
- [Rate limits](https://pixelsystems.com/docs/api/rate-limits): request limits, the rate limit headers, and how to retry.
- [Error codes](https://pixelsystems.com/docs/api/error-codes): the error envelope and what every code means.
- [Resources](https://pixelsystems.com/docs/api/resources): the objects the API returns and how they reference each other.
- [Assess a file](https://pixelsystems.com/docs/api/assess) (`/v1/assess`): verify a file, or up to 20 files of one case, in one call.
- [Get a job's result](https://pixelsystems.com/docs/api/get-job) (`/v1/jobs/{jobId}`): read a job's status and per-file results.
- [List jobs](https://pixelsystems.com/docs/api/list-jobs) (`/v1/jobs`): browse previous submissions.

See also [Concepts](https://pixelsystems.com/docs/concepts) for how applications, jobs, and files relate.