# Verae Time API (for the Zapier connector)

Live docs:

- Swagger UI: https://api.veraetime.net/docs/swagger/index.html
- OpenAPI 3.0: https://api.veraetime.net/docs/swagger/openapi.yaml
- Local copy: [openapi.yaml](openapi.yaml)

Title in the spec is still “Timestamping Service API”. Host is **https://api.veraetime.net** (`servers.url` is `/`).

## Auth

`POST /auth/login` with `{ username, password }` → JWT in `token`.  
All other API/admin routes: `Authorization: Bearer <token>`.  
Zapier mapping: **session auth** (`scratch/veraetime`).

## Two hops

Zapier should call **verae-zapier-middleware**, not this host directly.

| Layer | Where | Role |
|-------|--------|------|
| Zapier connector | `scratch/veraetime` | Session auth + Zapier operations |
| Middleware | `verae-zapier-api/verae-zapier-middleware` (also at `/Users/marchon/datacubes/verae-zapier-api/…`) | Tenants, API keys, rate limits, REST Hooks, wait-for-job, NATS workers |
| Verae Time | `https://api.veraetime.net` | Blockchain timestamping (this OpenAPI) |

Middleware routes (all under `/zapier/v1`):

| Method | Path | Connector |
|--------|------|-----------|
| POST | `/auth/login` | session `perform` (`username`/`password` or `api_key`) |
| GET | `/auth/me` | auth test |
| POST | `/timestamp` | Create Timestamp |
| POST | `/timestamp/wait` | Create Timestamp and Wait |
| POST | `/timestamp/batch` | Create Batch Timestamps |
| POST | `/verify` | Verify Certificate |
| GET | `/status/{jobId}` | Find Job Status |
| GET | `/status/{jobId}/verification` | Find Job Verification |
| POST | `/webhooks/subscribe` | Timestamp Completed (hook subscribe) |
| DELETE | `/webhooks/unsubscribe` | hook unsubscribe |

## Direct Verae mapping (what the middleware wraps)

| Zapier | Verb | Path | Notes |
|--------|------|------|--------|
| Create Timestamp | POST | `/api/timestamp` | `{ data, hashAlg? }` → `{ jobId }` (HTTP 202) |
| Create Batch Timestamps | POST | `/api/batch/timestamp` | `{ items: [{ data, hashAlg? }] }` |
| Verify Certificate | POST | `/api/verify` | `{ certificate }` → `{ valid, timestamp, blockIndex }` |
| Find Job Status | GET | `/api/status/{jobId}` | Search; empty if 404 |
| Find Job Verification | GET | `/api/verify/{jobId}` | Search |
| New Blockchain Timestamp | GET | `/admin/timestamps` | Polling trigger (admin; last ~10 blocks) |

Not in v1 (admin HTML / user admin): dashboard HTML, metrics, queue, list/create/update/delete users, batch verify/status, get-block-by-hash. Easy to add later.