Assess a file

Assess a single file in one call: upload it as multipart/form-data and receive the verdict in the same request. By default the call waits (long-polls) until analysis finishes; it returns 202 with a processing envelope if the wait window elapses first.

MethodPOST

Endpoint/v1/assess

Headers

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. 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.	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	object	Overall verdict for a completed job, with per-dimension breakdown. Present only when status is completed.
verdict.assessment	string	Headline, customer-actionable assessment (e.g. ai_generated).
verdict.confidence	ConfidenceLevel	Qualitative confidence in an assessment.
verdict.display	object	Rendered copy for assessment. Present for every completed run.
verdict.display.label	string	Short badge or table-cell copy, e.g. Inconclusive.
verdict.display.title	string	Headline for the main result indicator.
verdict.display.description	string	Supporting sentence shown under the headline.
verdict.dimensions	array<Dimension>
verdict.dimensions[].key	string	Stable identifier of the dimension, e.g. ai_detection.
verdict.dimensions[].label	string	Human-readable name of the dimension.
verdict.dimensions[].assessment	string	Aggregated assessment for this dimension.
verdict.dimensions[].score	number	Aggregated numeric score in [0, 1].
verdict.dimensions[].confidence	ConfidenceLevel	Qualitative confidence in an assessment.
error	object	Why a job ended in error or rejected status; present only for those statuses. Uses the same code vocabulary as endpoint errors.
error.code	ErrorCode	Stable machine-readable error code. The same vocabulary is used by every endpoint and by jobs in error or rejected status.
error.message	string
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. The "file" part is required (JPEG, PNG, or HEIC/HEIF, at most 25 MB); the optional "metadata" part is a JSON-encoded object echoed back on the job. The optional Idempotency-Key header (1–255 characters) makes retries safe: a repeated key returns the existing job instead of creating a duplicate. The "wait" query parameter defaults to true and long-polls up to 30 seconds — a 200 response carries a terminal status (completed or error), a 202 means still processing; poll GET /v1/jobs/{jobId} (which supports the same "wait" parameter) until the status leaves processing.