Assess a file

Assess a single file in one call: upload it as multipart/form-data and get the verdict in the same request, or a 202 envelope if the wait window elapses.

POST /v1/assess

Request

POST /v1/assess
Authorization: Bearer {api_key}
Content-Type: multipart/form-data; boundary={set by your HTTP client}

Header parameters

Header	Type	Description	Required
Idempotency-Key	`string`	Optional idempotency key, 1–255 characters. Retrying a submission with the same key returns the original job instead of creating a duplicate.	No

Query parameters

Parameter	Type	Description	Required
wait	`boolean`	Block until the job completes. `true` (the default) waits up to 30 s before falling back to the polling response; `false` returns immediately. Changes response timing and HTTP status only — never the result shape.	No

Body parameters

Parameter	Type	Description	Required
file	`string (binary)`	The file to assess: JPEG, PNG, or HEIC/HEIF, at most 25 MB.	Yes
metadata	`string`	Optional JSON-encoded object, echoed back verbatim as `metadata` on the result.	No

Example request

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"}'

Response (200)

Assessment completed within the wait window

Field	Type	Description
jobId	`string (uuid)`	Single job identity, shared by every path that references this job.
status	`JobStatus`	Lifecycle status of a job. `verdict` is present only when `completed`. `rejected` is reserved for future use and is not currently produced.
verdict	`Verdict`	Overall verdict for a completed job, with per-dimension breakdown. Present only when `status` is `completed`.
expertReview	`ExpertReview`	Present when a verification specialist has reviewed this job. Single-file jobs only.
error	`JobResultError`	Why a job ended in `error` or `rejected` status; present only for those statuses. Uses the same code vocabulary as endpoint errors.
metadata	`object`	Caller-supplied metadata, echoed back verbatim.
createdAt	`string (date-time)`	When the job was created (ISO 8601).
completedAt	`string (date-time)`	When processing finished (ISO 8601).

Example response

{
  "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"
}

Notes

The request body is multipart/form-data, not JSON: send file (and the optional metadata) as form parts, as in the example above. A 200 response carries a terminal status (completed or error); a 202 means the wait window elapsed first. Poll Get a job's result (/v1/jobs/{jobId}), which supports the same wait parameter, until the status leaves processing. When a verification specialist has reviewed the job (possible when an Idempotency-Key replay returns an earlier job), the response also carries an expertReview field while its status is completed; see ExpertReview for its shape.