Zegi API

Extract text and structured data from images and PDFs — synchronously or asynchronously — with usage metering, signed webhooks and predictable, versioned responses. UAE-first, built for websites, mobile apps, ERP/POS/accounting systems and AI agents.

Authentication

Create a key in your API dashboard. Send it as a bearer token on every request. The key is shown once — store it securely and never expose it in client-side code or query strings.

Authorization: Bearer ajk_live_xxx.ajs_xxx
# or:
X-API-Key: ajk_live_xxx.ajs_xxx

Quick start

1. Create an API key with the ocr:process scope.
2. POST a file to /ocr.
3. Read data.files[0].text from the response envelope.

curl -X POST "https://zegi.ae/api/v1/ocr" \
  -H "Authorization: Bearer $ZEGI_API_KEY" \
  -F "file=@document.png"

Every keyed response is wrapped in a consistent envelope:

{
  "success": true,
  "request_id": "req_9f2c1a7b3d4e5f60",
  "api_version": "v1",
  "data": {
    "files": [
      { "name": "document.png", "ok": true, "text": "…", "confidence": 96,
        "engine": "paddleocr", "language": "en", "document_type": "invoice",
        "structured": { /* invoice/receipt/passport when detected */ },
        "pages": [ { "page": 1, "text": "…", "confidence": 96 } ] }
    ]
  }
}

OCR

POST /ocr accepts multipart file (or files). Supported inputs: JPG, PNG, WEBP, and PDFs with a text layer. Add ?includeLayout=true for per-line bounding boxes. Recognized documents (invoice, receipt, passport) also return a typed structured object; uncertain fields are null — never fabricated.

Async jobs

For large files, submit with ?async=true to get a 202 and a job_id, then poll GET /ocr/jobs/{id}. Send an Idempotency-Key header to safely retry submissions without duplicating work.

# 1) Submit — returns 202 with a job_id
curl -X POST "https://zegi.ae/api/v1/ocr?async=true" \
  -H "Authorization: Bearer $ZEGI_API_KEY" \
  -H "Idempotency-Key: my-unique-key-001" \
  -F "file=@large.pdf"

# 2) Poll until status is "completed"
curl "https://zegi.ae/api/v1/ocr/jobs/JOB_ID" \
  -H "Authorization: Bearer $ZEGI_API_KEY"

Webhooks

Register an endpoint (POST /webhooks) to receive events. Each delivery is signed — verify the X-Zegi-Signature header (HMAC-SHA256 over `${timestamp}.${body}`) and reject timestamps older than 5 minutes. The legacy X-AjmanOCR-Signature header is still sent for backward compatibility.

Events: ocr.completedocr.failedtool.completedtool.failed

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, headers, secret) {
  const ts = headers["x-zegi-timestamp"] ?? headers["x-ajmanocr-timestamp"]; // legacy fallback
  const sig = headers["x-zegi-signature"] ?? headers["x-ajmanocr-signature"]; // "v1=<hex>"
  const expected = "v1=" + createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // replay window
  return sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Scopes

Errors

Errors use the same envelope with a stable error.code and an HTTP status. Never parse the message — switch on the code.

Rate limits & limits

• Max file size: 25 MB (admin-configurable).
• Max pages processed per document: 30.
• Page allowance & per-key rate limits depend on your plan — see GET /account.
• 1 image = 1 page; a PDF counts its text-layer pages.
• Rate-limited requests return 429 RATE_LIMITED; allowance exhaustion returns 429 USAGE_LIMIT_EXCEEDED.

AI integration guide

Building with an AI coding agent (Claude Code, Cursor, Lovable, Bolt, Replit, v0)? Point it at the machine-readable spec and paste this prompt. The agent will follow the real contract instead of guessing.

You are integrating the Zegi API into my application.
Read the OpenAPI specification at https://zegi.ae/api/openapi.json and follow it exactly.
Authenticate with 'Authorization: Bearer <API_KEY>'. Respect the documented scopes,
limits, error codes and the JSON response envelope. For large files submit with
?async=true and poll GET /ocr/jobs/{id}. Verify webhook signatures using the
X-Zegi-Signature header (the legacy X-AjmanOCR-Signature is also sent). Do not invent endpoints or parameters.

Machine-readable: openapi.json, openapi.yaml, llms.txt, llms-full.txt.

OpenAPI & SDKs

The full contract is published as OpenAPI 3.1. Generate a typed client in your language with any OpenAPI generator, or use the examples above directly.

# Example: generate a client from the spec
npx @openapitools/openapi-generator-cli generate \
  -i https://zegi.ae/api/openapi.json \
  -g typescript-fetch -o ./zegi-client

Changelog