GET/v1/verify/status/:sessionId

Check Status

Check the verification status of a session.

Description

This endpoint allows you to check the status of a verification session at any time. Use the session_id (which is the same as the challenge_id) to retrieve verification details.

This is useful for audit trails, status checking, or retrieving verification results after the fact.

Headers

Header	Value	Required
`X-Api-Key`	Your API key	✓

Path Parameters

Parameter	Type	Description
`sessionId`	string	The session ID (same as challenge_id)

Example Request

cURL

curl -X GET https://api.zeroproofai.com/v1/verify/status/ch_7x9k2a8f3e1d9c4b \
  -H "X-Api-Key: your_api_key_here"

JavaScript

const sessionId = 'ch_7x9k2a8f3e1d9c4b';

const response = await fetch(
  `https://api.zeroproofai.com/v1/verify/status/${sessionId}`,
  {
    headers: {
      'X-Api-Key': 'your_api_key_here'
    }
  }
);

const status = await response.json();
console.log('Status:', status.status);
console.log('Verified:', status.status === 'verified');

Response

Success Response (200 OK)

{
  "session_id": "ch_7x9k2a8f3e1d9c4b",
  "status": "verified",
  "agent_id": "shop-bot-001",
  "action": "purchase",
  "created_at": "2025-01-01T12:00:00Z",
  "verified_at": "2025-01-01T12:00:02Z",
  "confidence": 0.99,
  "expires_at": "2025-01-01T12:05:00Z"
}

Field	Type	Description
`session_id`	string	The session identifier
`status`	string	Status: "pending", "verified", "failed", or "expired"
`agent_id`	string	The agent identifier
`action`	string	The action being verified
`created_at`	string	ISO 8601 timestamp when challenge was created
`verified_at`	string \| null	ISO 8601 timestamp when verified (null if not verified)
`confidence`	number \| null	Confidence score (null if not verified)
`expires_at`	string	ISO 8601 timestamp when challenge expires

Status Values

Status	Description
`pending`	Challenge created but not yet verified
`verified`	Proof successfully verified
`failed`	Proof verification failed
`expired`	Challenge expired (> 5 minutes)

Error Responses

404 Not Found

{
  "error": "Session not found"
}

403 Forbidden

{
  "error": "Unauthorized access to session"
}

This error occurs when trying to access a session created with a different API key.

401 Unauthorized

{
  "error": "Missing API key",
  "message": "Provide API key in X-Api-Key header"
}

Use Cases

Audit Trail

Store session IDs in your database and query verification status for compliance and auditing purposes.

Async Verification

If verification happens asynchronously, poll this endpoint to check when verification completes.

Status Dashboard

Build dashboards that display verification statuses across multiple agents or transactions.

Notes

Session data is retained for 24 hours after expiration for audit purposes
You can only access sessions created with your API key
Status checks do not count against your API rate limits
The session_id is the same as the challenge_id

Complete Flow Example

Complete Verification Flow

// Step 1: Request challenge
const challengeResponse = await fetch(
  'https://api.zeroproofai.com/v1/verify/challenge',
  { method: 'POST', headers: {...}, body: {...} }
);
const challenge = await challengeResponse.json();

// Step 2: Generate and submit proof
const proof = generateProof(challenge.nonce);
const verifyResponse = await fetch(
  'https://api.zeroproofai.com/v1/verify/proof',
  { method: 'POST', headers: {...}, body: { challenge_id: challenge.challenge_id, proof } }
);
const result = await verifyResponse.json();

// Step 3: Check status anytime later
const statusResponse = await fetch(
  `https://api.zeroproofai.com/v1/verify/status/${result.session_id}`,
  { headers: { 'X-Api-Key': apiKey } }
);
const status = await statusResponse.json();
console.log('Final status:', status.status);