Verifications API

Every call to POST /v1/verify writes a row scoped to your account. These two endpoints read that history back: list verifications with filters and cursor pagination, and retrieve a single verification by ID with a freshly signed image URL. Both are read-only and account-scoped — you only ever see your own verifications.

Authentication

Both endpoints authenticate the same way as every VerifyAI request.

| Header | Required | Value | | ----------- | -------- | ------------------------------------------------------ | | X-API-Key | Yes | Your vai_… key. See Authentication. |

List verifications

text

GET /api/v1/verifications

Returns your most recent verifications, newest first, with cursor-based pagination. Use the query parameters to filter by policy, status, compliance, or date range.

Query parameters

| Parameter | Type | Default | Description | | -------------- | ------- | ------- | ---------------------------------------------------------------------------- | | limit | number | 20 | Page size. Clamped to a maximum of 100. | | cursor | string | — | Pagination cursor. Pass the next_cursor from the previous page. | | policy | string | — | Filter to a single policy ID (e.g. scooter_parking). | | status | string | — | Filter by success or error. | | is_compliant | boolean | — | Filter by outcome — true or false. | | start_date | string | — | ISO 8601 lower bound (inclusive) on created_at. | | end_date | string | — | ISO 8601 upper bound (inclusive) on created_at. |

Example

curl "https://verify.switchlabs.dev/api/v1/verifications?limit=20&policy=scooter_parking&is_compliant=false" \
-H "X-API-Key: vai_your_api_key"

Response

json

{
  "data": [
    {
      "id": "ver_8x92m4k9",
      "created_at": "2026-05-12T14:30:00Z",
      "status": "success",
      "is_compliant": false,
      "confidence": 0.94,
      "policy": "scooter_parking",
      "violation_reasons": ["blocking_sidewalk", "kickstand_up"],
      "feedback": "Please deploy the kickstand and move away from the walkway.",
      "metadata": { "trip_id": "trip_456" },
      "image_url": "https://...signed-url..."
    }
  ],
  "has_more": true,
  "next_cursor": "2026-05-12T14:30:00Z"
}

Response fields

| Field | Type | Description | | ------------- | -------- | --------------------------------------------------------------------------------- | | data | object[] | The page of verification summaries, newest first. | | has_more | boolean | true when more results exist past this page. | | next_cursor | string? | Pass as cursor to fetch the next page. null on the last page. |

Each item in data carries id, created_at, status, is_compliant, confidence, policy, violation_reasons, feedback, metadata, and a freshly signed image_url (null when storage is disabled).

List items omit category

The list endpoint returns a compact summary and does not include the category field. If you need the resolved category for a specific verification, fetch it from the retrieve endpoint below, or read it from the original POST /v1/verify response.

Paginating

next_cursor is the created_at of the last item on the page. Pass it back as cursor and keep going until has_more is false:

let cursor = null;
const all = [];
do {
const params = new URLSearchParams({ limit: "100" });
if (cursor) params.set("cursor", cursor);
const res = await fetch(
  "https://verify.switchlabs.dev/api/v1/verifications?" + params,
  { headers: { "X-API-Key": process.env.VERIFY_AI_KEY } },
);
const page = await res.json();
all.push(...page.data);
cursor = page.next_cursor;
} while (cursor);

Retrieve a verification

text

GET /api/v1/verifications/:id

Returns a single verification by its ver_ ID. The image URL is signed fresh on every call — use this endpoint when an image_url from an earlier response has expired.

Example

curl https://verify.switchlabs.dev/api/v1/verifications/ver_8x92m4k9 \
-H "X-API-Key: vai_your_api_key"

Response

json

{
  "id": "ver_8x92m4k9",
  "created_at": "2026-05-12T14:30:00Z",
  "status": "success",
  "is_compliant": false,
  "confidence": 0.94,
  "policy": "scooter_parking",
  "violation_reasons": ["blocking_sidewalk", "kickstand_up"],
  "feedback": "Please deploy the kickstand and move away from the walkway.",
  "metadata": { "trip_id": "trip_456" },
  "image_url": "https://...signed-url...",
  "processing_time_ms": 1184,
  "error_message": null
}

Response fields

| Field | Type | Description | | -------------------- | -------- | ---------------------------------------------------------------------------- | | id | string | The verification ID, prefix ver_. | | created_at | ISO 8601 | When the verification was processed. | | status | string | success or error. | | is_compliant | boolean | Top-level pass/fail decision. | | confidence | number | 0–1 confidence score from the underlying model. | | policy | string | The policy ID that ran. | | violation_reasons | string[] | Machine-readable IDs of the failed criteria. | | feedback | string | Human-readable explanation, safe to surface to end users. | | metadata | object | The metadata you sent with the original request. | | image_url | string? | Freshly signed URL to the stored image. null if storage is disabled. | | processing_time_ms | number? | Server-side processing time for the original verification. | | error_message | string? | Populated when status is error; otherwise null. |

Errors

| Status | Reason | | ------ | ------------------------------------------------------------------- | | 401 | Missing or invalid API key. | | 403 | API key not valid for VerifyAI, or not linked to a customer. | | 404 | Verification not found, or it belongs to a different account (retrieve). | | 429 | Rate limit — check the Retry-After header. | | 500 | Failed to fetch verifications. | | 503 | Authentication service unavailable. Retry. |

What's next

Verify endpoint — create verifications; full request and response schema.
Concepts: Verifications — the verification object, lifecycle, and retention.
Policies API — fetch the runtime config a policy uses.

Get in Touch