Resources
The objects the API returns and how they reference each other. Endpoint pages link each field's type to its definition here.
JobResult
The v1 job result. The same object is returned by the synchronous response, the poll, and every future result surface.
| Field | Type | Description | Required |
|---|---|---|---|
| jobId | string (uuid) | Single job identity, shared by every path that references this job. | Yes |
| status | JobStatus | Lifecycle status of a job, derived from results[].status: processing while any result is processing, then error if any result errored, otherwise completed. A job with no files is processing. Each result carries its own verdict once completed. rejected is reserved for future use and is not currently produced. | Yes |
| results | array<FileResult> | One result per submitted file, in submission order. This is the job's result; read each entry's status, verdict, and expertReview. There is no job-level verdict: two files in one job can reach opposite assessments. | Yes |
| error | JobResultError | Why a job or one of its results ended in error (or a job in rejected) status; present only for those statuses. Uses the same code vocabulary as endpoint errors. On the job it is derived from the results: result_unavailable when every errored result carries that code, otherwise internal_error. | No |
| metadata | object | Caller-supplied metadata, echoed back verbatim. Absent when the submission carried none. | No |
| createdAt | string (date-time) | When the job was created (ISO 8601). | Yes |
| completedAt | string (date-time) | When processing finished (ISO 8601). Absent while the job is processing. | No |
FileResult
One file's result. status selects the shape: a completed result carries verdict and dimensions, an error result carries error, a processing result carries neither.
One of ProcessingResult, CompletedResult, ErrorResult, selected by status.
ProcessingResult
The analysis has not reached a terminal state.
| Field | Type | Description | Required |
|---|---|---|---|
| status | "processing" | The analysis has not reached a terminal state; poll again. | Yes |
| file | ResultFile | The file a result describes. | Yes |
| startedAt | string (date-time) | null | When the analysis started (ISO 8601); null until it does. | Yes |
| completedAt | string (date-time) | null | When the analysis reached a terminal state (ISO 8601); null while processing. | Yes |
CompletedResult
The analysis finished and a verdict is available.
| Field | Type | Description | Required |
|---|---|---|---|
| status | "completed" | The analysis finished; verdict and dimensions are set. | Yes |
| file | ResultFile | The file a result describes. | Yes |
| startedAt | string (date-time) | null | When the analysis started (ISO 8601); null until it does. | Yes |
| completedAt | string (date-time) | null | When the analysis reached a terminal state (ISO 8601); null while processing. | Yes |
| verdict | ResultVerdict | The headline result for one file: the assessment the pipeline's verdict policy selected from the dimensions, and how sure it is. | Yes |
| dimensions | array<ResultDimension> | The axes of analysis behind the verdict, each with its own result. Dimensions that flagged the file come first, then the rest in the pipeline's order. | Yes |
| expertReview | ResultExpertReview | Present when a specialist review was requested for this file. | No |
ErrorResult
The analysis failed, or its stored result cannot be served. Re-submit the file for a current result.
| Field | Type | Description | Required |
|---|---|---|---|
| status | "error" | The analysis failed or cannot be served; error says why. | Yes |
| file | ResultFile | The file a result describes. | Yes |
| startedAt | string (date-time) | null | When the analysis started (ISO 8601); null until it does. | Yes |
| completedAt | string (date-time) | null | When the analysis reached a terminal state (ISO 8601); null while processing. | Yes |
| error | JobResultError | Why a job or one of its results ended in error (or a job in rejected) status; present only for those statuses. Uses the same code vocabulary as endpoint errors. On the job it is derived from the results: result_unavailable when every errored result carries that code, otherwise internal_error. | Yes |
ResultFile
The file a result describes.
| Field | Type | Description | Required |
|---|---|---|---|
| id | string (uuid) | Identifier of the file; use it to pick this entry out of results[] when a job has several files. | Yes |
| name | string | File name as submitted. | Yes |
| size | integer | File size in bytes. | Yes |
| type | string | MIME type as submitted, e.g. image/jpeg. | Yes |
ResultStatus
Status of one file's result. processing until the analysis reaches a terminal state; completed when a verdict is available; error when the analysis failed (internal_error) or its stored result cannot be served (result_unavailable). The job's status is derived from these: processing while any result is processing, then error if any result errored, otherwise completed.
Values: processing, completed, error
ResultVerdict
The headline result for one file: the assessment the pipeline's verdict policy selected from the dimensions, and how sure it is.
| Field | Type | Description | Required |
|---|---|---|---|
| assessment | Assessment | null | Headline assessment for this file. null when the stored result carries no headline key. | Yes |
| confidence | ConfidenceLevel | How sure the analysis is of the enclosing assessment: high, medium, or low. Folded from the detectors' numeric confidence; a specialist states it directly on a review. | Yes |
ResultDimension
One axis of analysis with its own result. key selects the shape: dimensions with structured evidence carry it under data.
One of AiDetectionDimension, ManipulationDetectionDimension, ReverseImageSearchDimension, CameraOriginDimension, DocumentProvenanceDimension, AiTextDetectionDimension, selected by key.
AiDetectionDimension
Signs of AI generation in the image.
| Field | Type | Description | Required |
|---|---|---|---|
| key | "ai_detection" | Which axis of analysis this is: signs of AI generation in the image. | Yes |
| score | number | How strongly the image reads as AI-generated, 0 to 1, as the pipeline's AI-detection model scores it. Near 0 reads as authentic; assessment states the call. | Yes |
| assessment | Assessment | ai_generated, likely_ai, uncertain, likely_authentic, or authentic. Absent when the analysis produced none. | No |
| confidence | ConfidenceLevel | How sure the analysis is of the enclosing assessment: high, medium, or low. Folded from the detectors' numeric confidence; a specialist states it directly on a review. | No |
| data | AiDetectionData | Structured evidence behind the AI detection score. Present only when the file carried a content credential that verified. | No |
ManipulationDetectionDimension
Signs of local editing or tampering.
| Field | Type | Description | Required |
|---|---|---|---|
| key | "manipulation_detection" | Which axis of analysis this is: signs of local editing or tampering. | Yes |
| score | number | How strongly the image reads as locally edited or tampered, 0 to 1. Near 0 reads as untouched; assessment states the call. | Yes |
| assessment | Assessment | manipulated, likely_manipulated, uncertain, or authentic. Absent when the analysis produced none. | No |
| confidence | ConfidenceLevel | How sure the analysis is of the enclosing assessment: high, medium, or low. Folded from the detectors' numeric confidence; a specialist states it directly on a review. | No |
ReverseImageSearchDimension
Whether the image, or a close copy, exists online.
| Field | Type | Description | Required |
|---|---|---|---|
| key | "reverse_image_search" | Which axis of analysis this is: whether the image, or a close copy, exists online. | Yes |
| score | number | The confidence of the closest candidate the search found, 0 to 1; 0 when it found none. data.matches lists only candidates above the search's similarity floor, so a low score can come with an empty list. | Yes |
| assessment | Assessment | found_online or not_found. Absent when the analysis produced none. | No |
| confidence | ConfidenceLevel | How sure the analysis is of the enclosing assessment: high, medium, or low. Folded from the detectors' numeric confidence; a specialist states it directly on a review. | No |
| data | ReverseImageSearchData | Structured evidence behind the reverse image search score: the matches found. | Yes |
CameraOriginDimension
Whether the file is an original camera capture.
| Field | Type | Description | Required |
|---|---|---|---|
| key | "camera_origin_verification" | Which axis of analysis this is: whether the file is an original camera capture. | Yes |
| score | number | 1 when the file's capture metadata is consistent with an original camera photo and every critical check passed, 0 when it is not. | Yes |
| assessment | Assessment | camera_origin or no_camera_origin. Absent when the analysis produced none. | No |
| confidence | ConfidenceLevel | How sure the analysis is of the enclosing assessment: high, medium, or low. Folded from the detectors' numeric confidence; a specialist states it directly on a review. | No |
| data | CameraOriginData | Structured evidence behind the camera origin score. Present only when the file's metadata names a camera. | No |
DocumentProvenanceDimension
Where a document came from and how it was produced.
| Field | Type | Description | Required |
|---|---|---|---|
| key | "document_provenance" | Which axis of analysis this is: where a document came from and how it was produced. | Yes |
| score | number | How suspicious the document's origin and production look, 0 to 1. Near 0 reads as authentic, near 1 as AI-produced; assessment states the call. | Yes |
| assessment | Assessment | ai_generated, uncertain, or authentic. Absent when the analysis produced none. | No |
| confidence | ConfidenceLevel | How sure the analysis is of the enclosing assessment: high, medium, or low. Folded from the detectors' numeric confidence; a specialist states it directly on a review. | No |
AiTextDetectionDimension
Signs of AI-written text in a document.
| Field | Type | Description | Required |
|---|---|---|---|
| key | "ai_text_detection" | Which axis of analysis this is: signs of AI-written text in a document. | Yes |
| score | number | How strongly the document's text reads as AI-written, 0 to 1. Near 0 reads as human-written, near 1 as AI-generated; assessment states the call. | Yes |
| assessment | Assessment | ai_generated, uncertain, or authentic. Absent when the analysis produced none. | No |
| confidence | ConfidenceLevel | How sure the analysis is of the enclosing assessment: high, medium, or low. Folded from the detectors' numeric confidence; a specialist states it directly on a review. | No |
AiDetectionData
Structured evidence behind the AI detection score. Present only when the file carried a content credential that verified.
| Field | Type | Description | Required |
|---|---|---|---|
| provenance | Provenance | A content credential that verified AI generation, as the file carried it. | Yes |
Provenance
A content credential that verified AI generation, as the file carried it.
| Field | Type | Description | Required |
|---|---|---|---|
| issuer | string | Who signed the content credential. | No |
| generator | string | The tool the credential names as the generator. | No |
ReverseImageSearchData
Structured evidence behind the reverse image search score: the matches found.
| Field | Type | Description | Required |
|---|---|---|---|
| matches | array<WebMatch> | Where the image was found online, highest confidence first. Empty when nothing was found. | Yes |
WebMatch
One place the image, or a close copy, was found online.
| Field | Type | Description | Required |
|---|---|---|---|
| url | string (uri) | Page the image appears on. | Yes |
| imageUrl | string (uri) | The matched image itself, when the source exposes it. | No |
| source | string | Host of the match, e.g. example.com. | Yes |
| title | string | Page title, as the source reported it. | No |
| confidence | number | How closely the found image resembles the submitted one, from 0 to 1: a copy scores near 1, a related but different image lower. Only candidates above the search's similarity floor are returned, ordered highest first. | Yes |
CameraOriginData
Structured evidence behind the camera origin score. Present only when the file's metadata names a camera.
| Field | Type | Description | Required |
|---|---|---|---|
| camera | Camera | The camera the file's metadata names. | Yes |
Camera
The camera the file's metadata names.
| Field | Type | Description | Required |
|---|---|---|---|
| make | string | Camera make from the file's metadata. | No |
| model | string | Camera model from the file's metadata. | No |
DimensionKey
Stable identifier of an axis of analysis.
Values: ai_detection, manipulation_detection, reverse_image_search, camera_origin_verification, document_provenance, ai_text_detection
Assessment
Stable machine key for an assessment, e.g. ai_generated, authentic, camera_origin, found_online. The vocabulary is per pipeline and per dimension; branch on the key, never on any wording.
Type: string
ResultExpertReview
Present when a specialist review was requested for this file.
One of ResolvedExpertReview, PendingExpertReview, selected by status.
ResolvedExpertReview
A review the specialist has completed.
| Field | Type | Description | Required |
|---|---|---|---|
| status | "resolved" | The specialist has completed the review. | Yes |
| requestNotes | string | null | The note your user wrote when requesting the review; null when they left none. | Yes |
| submittedAt | string (date-time) | When the review was requested (ISO 8601). | Yes |
| result | ExpertReviewResult | A verification specialist's resolved findings for one file. | Yes |
PendingExpertReview
A review that has no findings to report yet, or never will.
| Field | Type | Description | Required |
|---|---|---|---|
| status | "new" | "in_progress" | "dismissed" | Where the request stands: new until a specialist picks it up, in_progress while they work, dismissed when it was closed without findings. | Yes |
| requestNotes | string | null | The note your user wrote when requesting the review; null when they left none. | Yes |
| submittedAt | string (date-time) | When the review was requested (ISO 8601). | Yes |
ExpertReviewResult
A verification specialist's resolved findings for one file.
| Field | Type | Description | Required |
|---|---|---|---|
| verdict | ExpertReviewVerdict | The specialist's overall verdict, present when they overrode it. The result's own verdict keeps the automated headline either way. | No |
| dimensions | array<ExpertReviewDimension> | The dimensions the specialist overrode, each with their call. Dimensions not listed stand as the automated analysis reported them. | Yes |
| confidence | ConfidenceLevel | The specialist's confidence in this review. | Yes |
| notes | string | The specialist's note to you, when they left one. | No |
| reviewedAt | string (date-time) | When the review was completed (ISO 8601). | Yes |
ExpertReviewVerdict
The specialist's overall verdict, present when they overrode it. The result's own verdict keeps the automated headline either way.
| Field | Type | Description | Required |
|---|---|---|---|
| assessment | Assessment | Stable machine key for an assessment, e.g. ai_generated, authentic, camera_origin, found_online. The vocabulary is per pipeline and per dimension; branch on the key, never on any wording. | Yes |
ExpertReviewDimension
One dimension the specialist overrode. Dimensions not listed stand as the automated analysis reported them.
| Field | Type | Description | Required |
|---|---|---|---|
| key | DimensionKey | Stable identifier of an axis of analysis. | Yes |
| assessment | Assessment | Stable machine key for an assessment, e.g. ai_generated, authentic, camera_origin, found_online. The vocabulary is per pipeline and per dimension; branch on the key, never on any wording. | Yes |
ReviewStatus
Where a requested specialist review stands. result is present only when resolved.
Values: new, in_progress, resolved, dismissed
ConfidenceLevel
How sure the analysis is of the enclosing assessment: high, medium, or low. Folded from the detectors' numeric confidence; a specialist states it directly on a review.
Values: high, medium, low
JobStatus
Lifecycle status of a job, derived from results[].status: processing while any result is processing, then error if any result errored, otherwise completed. A job with no files is processing. Each result carries its own verdict once completed. rejected is reserved for future use and is not currently produced.
Values: processing, completed, error, rejected
JobSummary
One job in a list: jobId, status, metadata, createdAt, and completedAt, each as JobResult defines it. The status is the same derived status the job's result reports; GET /v1/jobs/{jobId} adds results[] and, for an errored job, error.
| Field | Type | Description | Required |
|---|---|---|---|
| jobId | string (uuid) | Single job identity, shared by every path that references this job. | Yes |
| status | JobStatus | Lifecycle status of a job, derived from results[].status: processing while any result is processing, then error if any result errored, otherwise completed. A job with no files is processing. Each result carries its own verdict once completed. rejected is reserved for future use and is not currently produced. | Yes |
| metadata | object | Caller-supplied metadata, echoed back verbatim. Absent when the submission carried none. | No |
| createdAt | string (date-time) | When the job was created (ISO 8601). | Yes |
| completedAt | string (date-time) | When processing finished (ISO 8601). Absent while the job is processing. | No |
PaginationMeta
Page-based pagination metadata for list responses.
| Field | Type | Description | Required |
|---|---|---|---|
| page | integer | The page this response contains, counted from 1. | Yes |
| pageSize | integer | Number of jobs per page used for this response. | Yes |
| total | integer | Total number of jobs across all pages. | Yes |
| totalPages | integer | Total number of pages at this pageSize. | Yes |
| hasNextPage | boolean | true when a page after this one exists. | Yes |
JobResultError
Why a job or one of its results ended in error (or a job in rejected) status; present only for those statuses. Uses the same code vocabulary as endpoint errors. On the job it is derived from the results: result_unavailable when every errored result carries that code, otherwise internal_error.
| Field | Type | Description | Required |
|---|---|---|---|
| code | ErrorCode | Stable machine-readable error code. The same vocabulary is used by every endpoint, by jobs in error or rejected status, and by a result in error status. result_unavailable is a result-only code: the analysis finished but its stored result cannot be served — re-submit the file. | Yes |
| message | string | A fixed sentence for the code, for logs and support tickets. Branch on code, not on this text. | Yes |
ApiError
Standard error response returned by every public endpoint.
| Field | Type | Description | Required |
|---|---|---|---|
| code | ErrorCode | Stable machine-readable error code. The same vocabulary is used by every endpoint, by jobs in error or rejected status, and by a result in error status. result_unavailable is a result-only code: the analysis finished but its stored result cannot be served — re-submit the file. | Yes |
| message | string | Human-readable explanation of the error. | Yes |
| details | ApiErrorDetails | Structured context for an error that names what in the request was wrong. Present on invalid_request and unprocessable errors that can point at a field; absent otherwise. | No |
| retryAfter | integer | Seconds to wait before retrying. Set for rate_limited and service_unavailable. | No |
ApiErrorDetails
Structured context for an error that names what in the request was wrong. Present on invalid_request and unprocessable errors that can point at a field; absent otherwise.
| Field | Type | Description | Required |
|---|---|---|---|
| issues | array<ApiErrorIssue> | Every problem found, one entry each. | Yes |
ApiErrorIssue
One thing wrong with the request.
| Field | Type | Description | Required |
|---|---|---|---|
| path | string | Where in the request the problem is, as a dotted path such as metadata.claimId; empty when it concerns the request as a whole. | Yes |
| message | string | What is wrong at that path, for logs and support. | No |
| code | string | The validator's own code for the problem, e.g. invalid_format. | No |
ErrorCode
Stable machine-readable error code. The same vocabulary is used by every endpoint, by jobs in error or rejected status, and by a result in error status. result_unavailable is a result-only code: the analysis finished but its stored result cannot be served — re-submit the file.
Values: invalid_request, unsupported_format, unauthorized, forbidden, not_found, file_too_large, unprocessable, rate_limited, internal_error, service_unavailable, result_unavailable
See Error codes for what each code means and how to respond.