API Reference

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, JSON responses, and standard HTTP response codes and verbs. Every request authenticates with an API key; see Authentication.

Base URL

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 OpenAPI spec:

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

TypeScript SDKs are available on request.

Workflow

The fastest way to verify a single file is one call to Assess a file (/v1/assess): upload the file as multipart/form-data. The call waits for analysis by default and responds 200 with the verdict when it finishes inside the wait window; otherwise it returns 202 with a processing status and you poll the job until it completes.

To read a result later, call Get a job's result (/v1/jobs/{jobId}) and poll until the job's status leaves processing. It ends as completed (with a verdict) or error. A job stays in processing until analysis finishes, which takes longer when the platform is busy. 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 (/v1/jobs) to browse previous submissions.

Example request

Send the file with your API key:

curl -X POST "https://api.pixelsystems.com/v1/assess" \
  -H "Authorization: Bearer {api_key}" \
  -H "Idempotency-Key: case-123-front-photo" \
  -F "file=@photo.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 and its verdict:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "verdict": {
    "assessment": "ai_generated",
    "confidence": "high",
    "display": {
      "label": "AI Generated",
      "title": "AI Generated",
      "description": "AI Generated image detected"
    },
    "dimensions": [
      {
        "key": "ai_detection",
        "label": "AI generation",
        "assessment": "likely_ai",
        "score": 0.82,
        "confidence": "high"
      }
    ]
  },
  "metadata": { "customer_case_id": "case-123" },
  "createdAt": "2024-06-01T12:00:00Z",
  "completedAt": "2024-06-01T12:00:14Z"
}

The verdict carries the assessment, a confidence level, and a per-dimension breakdown. Field-by-field documentation lives in Verdict.

Explore the reference

  • Authentication: API keys and the Authorization header.
  • Rate limits: request limits, the rate limit headers, and how to retry.
  • Error codes: the error envelope and what every code means.
  • Resources: the objects the API returns and how they reference each other.
  • Assess a file (/v1/assess): verify a file in one call.
  • Get a job's result (/v1/jobs/{jobId}): read a job's status and verdict.
  • List jobs (/v1/jobs): browse previous submissions.

See also Concepts for how applications, jobs, and files relate.