API Reference

Base URL: https://api.verimago.io

All requests use JSON. All responses return JSON. CORS is enabled for all origins.

Authentication

Most endpoints require a Bearer token. Obtain one by logging in or using a persistent API key.

Authorization: Bearer <token-or-api-key>

Auth

POST /v1/auth/register

Create a new account.

{
  "email": "user@example.com",
  "password": "min-8-characters",
  "name": "Jane Smith"
}

{
  "message": "Verification email sent",
  "userId": "usr_abc123"
}

POST /v1/auth/verify-email

Verify email address using the code sent during registration.

{
  "email": "user@example.com",
  "code": "123456"
}

POST /v1/auth/login

Request body uses username (for normal accounts this is your email address), not email.

{
  "username": "user@example.com",
  "password": "your-password"
}

{
  "token": "vmgo_...",
  "passwordChangeRequired": false
}

When passwordChangeRequired is true, the client should send the user to change password (publisher portal: Settings) before normal browsing; GET /v1/user/me echoes the same flag until POST /v1/user/me/password succeeds.

Use Authorization: Bearer on protected routes. If SMS MFA is enabled, you may get mfaRequired and mfaToken instead of token until you complete POST /v1/auth/mfa/verify. If the account has no certificate yet, you may get needsCert: true with a token for onboarding.

POST /v1/auth/forgot-password

{ "email": "user@example.com" }

POST /v1/auth/reset-password

{
  "email": "user@example.com",
  "code": "123456",
  "newPassword": "new-password"
}

Identities (social links — named Creator certs roadmap)

GET /v1/identities

Returns linked social identities (active only). Empty array until the user completes OAuth link flows (Phase 1).

{
  "identities": [
    {
      "id": "uuid",
      "provider": "instagram",
      "providerUserId": "178414053…",
      "username": "@handle",
      "displayName": "Display Name",
      "profileUrl": "https://…",
      "profileImage": "https://…",
      "verifiedAt": "2026-04-18T12:00:00.000Z",
      "isPrimary": true
    }
  ]
}

PATCH /v1/identities/{id}/primary

Sets the given identity as primary (clears isPrimary on others). 404 if the id does not belong to the caller.

DELETE /v1/identities/{id}

Soft-revokes the link (revoked_at). Promotes the oldest remaining identity to primary when needed.

First-party Verimago @handle (verimago_handle)

GET /v1/user/me/handle

PUT /v1/user/me/handle

OAuth (Google live; other providers stubbed)

GET /v1/oauth/{provider}/authorize

GET /v1/oauth/{provider}/callback

Publisher domain validation (DNS TXT)

POST /v1/domains/validate

{ "domain": "example.com", "method": "dns_txt" }

POST /v1/domains/check

Full design: docs/HANDOFF_OAUTH_NAMED_CERTS.md, architecture: docs/architecture/OAUTH_NAMED_CERTS_AND_DOMAIN_VALIDATION.md.

Sign (Server-Side)

POST /v1/sign

Sign a content hash using the Verimago CA. The video/photo file is never uploaded — only the SHA-384 hash (96 hex).

{
  "contentHash": "38b060a751ac96384cd9327eb1b1e36a21fdb71114be07434c0cc7bf63f6e1da274edebfe76f65fbd51ad2f14898b95b",
  "headline": "Breaking: City council vote",
  "journalist": "Jane Smith",
  "location": "Portland, OR",
  "recordedAt": "2026-03-28T14:30:00Z",
  "contentType": "AUTHENTIC",
  "captureMode": "VIDEO",
  "tags": ["politics", "local"]
}

{
  "contentHash": "38b060a751ac96384cd9327eb1b1e36a21fdb71114be07434c0cc7bf63f6e1da274edebfe76f65fbd51ad2f14898b95b",
  "certId": "550e8400-e29b-41d4-a716-446655440000",
  "signature": "MEUCIQ...",
  "shieldState": "GREEN",
  "signedAt": "2026-03-28T15:00:00.000Z",
  "contentType": "AUTHENTIC",
  "verifyUrl": "https://registry.verimago.io/v/?h=38b060a751ac"
}

• 402 — No subscription / no unused freelance credit for this hash.
• 409 — Manifest already exists; body may include existing with prior verifyUrl and fields.

POST /v1/stripe/checkout-onetime

GET /v1/stripe/freelance-purchase

Verify (Public)

GET /v1/verify/{hash}

Look up a certificate by content hash. Path {hash} may be full sha384: / sha256: + hex, plain 64- or 96-char hex, or an 8–95 character hex prefix (prefix resolves to the first matching manifest).

GET /v1/verify/sha384:38b060a751ac96384cd9327eb1b1e36a21fdb71114be07434c0cc7bf63f6e1da274edebfe76f65fbd51ad2f14898b95b
GET /v1/verify/38b060a751ac

{
  "verified": true,
  "shieldState": "GREEN",
  "publisher": "Reuters",
  "journalist": "Jane Smith",
  "headline": "Breaking: City council vote",
  "location": "Portland, OR",
  "signedAt": "2026-03-28T15:00:00Z",
  "recordedAt": "2026-03-28T14:30:00Z",
  "contentType": "AUTHENTIC",
  "certStatus": "ACTIVE"
}

{
  "verified": false,
  "shieldState": "GREY"
}

POST /v1/verify/url

Verify content by URL. The server fetches the file, computes the hash, and looks it up.

{
  "url": "https://example.com/video.mp4"
}

Rate limited to 10 requests per IP per minute. Maximum file size: 500 MB. Timeout: 25 seconds.

API Keys

GET /v1/keys

List all active API keys for your account.

{
  "items": [
    {
      "id": "key_abc123",
      "name": "CMS Production",
      "keyPrefix": "vmgo_xxxxxxx",
      "createdAt": "2026-03-28T12:00:00Z",
      "lastUsedAt": "2026-03-28T15:00:00Z",
      "expiresAt": "2027-03-28T12:00:00Z"
    }
  ],
  "total": 1
}

POST /v1/keys

Generate a new API key. The full key is returned only once.

{ "name": "CMS Production" }

Optional automatic expiry (choose one; if both are sent, the request is rejected):

• ttlDays — integer from 1 to 365. The key stops working after that many days from creation (server wall clock).
• expiresAt — ISO 8601 instant in the future, at most 365 days after the request.

Omit both for a key that stays valid until revoked (same behavior as before this option existed).

{ "name": "CI — C2PA verify", "ttlDays": 90 }

{
  "id": "uuid",
  "name": "CMS Production",
  "raw": "vmgo_…",
  "prefix": "vmgo_xxxxxx",
  "expiresAt": "2026-06-26T12:00:00.000Z"
}

When no expiry was requested, expiresAt is null.

Use raw as Authorization: Bearer … and as apiKey in @verimago/sdk. The list endpoint returns only keyPrefix (first 12 characters of the key), not the full secret.

POST /v1/keys/{id}/revoke

Revoke an API key. Immediate effect — all requests using this key will fail.

Certificates

GET /v1/certs

List certificates associated with your account.

GET /v1/certs/{id}

Get certificate details including status, expiry, and public key.

PATCH /v1/certs/{id}/activate

Activate a pending certificate.

PATCH /v1/certs/{id}/revoke

Revoke a certificate. All manifests signed with this certificate will show the certificate as revoked during verification, though the signature remains valid.

Applications

POST /v1/apply

Submit a publisher or creator application.

{
  "organizationName": "Portland Herald",
  "contactEmail": "editor@portlandherald.com",
  "contactName": "Jane Smith",
  "domain": "portlandherald.com",
  "jurisdiction": "US-OR",
  "description": "Daily newspaper covering Portland metro area, 50,000 daily readers"
}

For creator applications, omit domain and organizationName.

{
  "id": "app_abc123",
  "status": "PENDING",
  "message": "Application received. You will be contacted within 48 hours."
}

GET /v1/apply/{id}

Check application status.

Watermark

POST /v1/watermark/upload-url

Get a presigned S3 URL to upload a video for watermarking.

{
  "filename": "my-video.mp4",
  "contentType": "video/mp4"
}

{
  "jobId": "wm_abc123",
  "uploadUrl": "https://s3.amazonaws.com/...",
  "expiresIn": 3600
}

POST /v1/watermark/process

Start watermark processing for an uploaded video.

{ "jobId": "wm_abc123" }

GET /v1/watermark/status/{jobId}

Check watermark processing status and get download URL when complete.

OCSP

These routes expose JSON for publisher TLS / account certificates in Verimago’s database. They are not RFC 6960 PKIX OCSP for the C2PA CA chain (issuer PEM + CRL for that chain are published at http://ca.verimago.io under /certs/ and /crl/ when operators sync the CA publication bucket).

GET /v1/ocsp/status

JSON health check. Response includes status: "ok" and a short note clarifying the separation from CA-chain OCSP.

GET /v1/ocsp/{certId}

Check publisher certificate revocation / expiry status (JSON fields such as GOOD / REVOKED / UNKNOWN), not DER OCSP.

TSA (timestamp proxy)

Verimago does not operate a Trusted Timestamp Authority. This API proxies RFC 3161 requests to the upstream service configured by TSA_URL. Default upstream in code and CDK is DigiCert’s public RFC 3161 endpoint http://timestamp.digicert.com (override with TSA_URL in GitHub staging / production environment secrets if a different DigiCert contract URL is required).

GET /v1/tsa/status

Health check for the timestamp proxy. Response includes the effective upstream TSA base URL (from TSA_URL or the built-in DigiCert default).

POST /v1/tsa

RFC 3161 proxy to the upstream TSA (DigiCert when TSA_URL is set correctly). Used by Verimago Camera (and integrators that mirror the same flow) during capture.

H=$(python3 -c "import base64,hashlib; print(base64.b64encode(hashlib.sha384(b'test').digest()).decode())")
curl -sS -w "\nHTTP %{http_code}\n" -X POST "https://api.verimago.io/v1/tsa" \
  -H "Content-Type: application/json" -d "{\"hash\":\"$H\"}" | head -c 200

Expect HTTP 200 and JSON with token and timestamp. HTTP 400 whose error text only allows 32-byte SHA-256 means the deployed Lambda is older than packages/api/src/routes/tsa.ts on main — redeploy the API before relying on new camera builds.

Operator admin (internal)

These routes are for operators using the publisher Admin UI or scripts. Authenticate with either:

• x-admin-secret: (same value as the ADMIN_SECRET environment variable on the API), or
• Authorization: Bearer for a user whose users.platform_role is superadmin (same capabilities as the shared secret for these operator routes).

Certificate admin actions use the same rule: PATCH /v1/certs/{id}/activate and PATCH /v1/certs/{id}/revoke. Application review (PATCH /v1/apply/{id}) and GET /v1/admin/applications likewise.

Apply DB migrations so users.disabled_at / users.disabled_reason / users.platform_role exist before relying on disable/enable or superadmin Bearer auth in production (packages/api/src/db/migrate-production.sql and admin migrate bundle). Bootstrap script: scripts/bootstrap-platform-superadmin.ts (see docs/SETUP.md).

Errors

All errors follow this format:

{
  "error": "Human-readable error message"
}

Rate limits