merlon API v1

A resource-oriented REST API for creating documents, provisioning secure vaults, orchestrating approval workflows, and reading tamper-evident audit logs. All requests are JSON over HTTPS, authenticated with a bearer token, and served from the region that matches your data-residency configuration.

Base URL

https://api.merlon.ch/v1

Regional URLs

https://api.us.merlon.ch/v1 · https://api.eu.merlon.ch/v1

Content type

application/json for request and response bodies

Timestamps

RFC 3339 / ISO 8601, always UTC (e.g. 2026-07-27T09:41:08Z)

Object IDs

Prefixed, opaque strings — doc_, vault_, wf_, evt_

Authentication

merlon supports two authentication schemes: API keys for server-to-server integrations, and OAuth2 for apps that act on behalf of a user. All requests must be made over HTTPS; calls over plain HTTP fail before reaching the application.

API keys

Pass your secret key as a bearer token. Keys are environment-scoped: sk_test_… hits the sandbox, sk_live_… hits production. Never expose a secret key in client-side code.

curl "https://api.merlon.ch/v1/documents" \
  -H "Authorization: Bearer sk_live_51Kf9c1Za8Xq2Wn4dPmR0"

OAuth2

For user-context apps, use the authorization-code flow. Exchange the code for an access token, then call the API with that token. Scopes map to the same permissions a user holds in the web app.

curl -X POST "https://api.merlon.ch/v1/oauth/token" \
  -d "grant_type=authorization_code" \
  -d "code=ac_9c1Za8Xq" \
  -d "client_id=cl_7Qd2" \
  -d "client_secret=cs_••••" \
  -d "redirect_uri=https://app.example.com/callback"

{
  "access_token": "at_5Rk21m…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "documents:write vaults:read"
}

Rate limits

Limits are applied per API key on a sliding one-minute window. Every response includes rate-limit headers so you can back off gracefully before you hit a wall.

When you exceed the limit the API returns 429 Too Many Requests with a Retry-After header (seconds). Response headers on every call: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Pagination

List endpoints are cursor-paginated. Pass limit (1–100, default 20) and follow next_cursor until it is null. Cursors are opaque and stable across inserts.

curl "https://api.merlon.ch/v1/documents?limit=20&cursor=cur_8Xq2Wn4d" \
  -H "Authorization: Bearer $MERLON_API_KEY"

{
  "object": "list",
  "data": [ /* … 20 documents … */ ],
  "has_more": true,
  "next_cursor": "cur_3kf9c1Za"
}

Errors

merlon uses conventional HTTP status codes. Codes in the 2xx range mean success, 4xx indicate a problem with your request, and 5xx indicate a problem on our side. Every error body carries a machine-readable type, a human message, and a request_id you can quote to support.

{
  "error": {
    "type": "permission_error",
    "message": "This key is missing the 'vaults:write' scope.",
    "request_id": "req_9c1Za8Xq"
  }
}

Versioning & deprecation policy

The API is versioned in the URL path (/v1). We add fields and endpoints without bumping the version — your integration should ignore unknown fields. Breaking changes only ship under a new major version.

Additive changes

New optional fields and endpoints may appear at any time within /v1. Treat responses as forward-compatible.

Deprecations

Announced in the changelog with at least a 12-month sunset window and a Sunset response header on affected endpoints.

Regional endpoints

Every version is available on all three hosts; residency is enforced at the edge regardless of host.

Documents

A document is a versioned file living inside a vault. Documents move through a lifecycle — draft → in_review → signed → locked — and every transition is recorded in the audit log.

Secure Vaults

A vault is an encrypted, access-scoped container for documents. Each vault has its own region, encryption envelope, and least-privilege member list.

Workflows

A workflow is an ordered set of approval steps attached to a document. Steps advance in sequence; each transition is captured with the actor, timestamp, and decision.

Audit Logs

Every action in merlon writes an immutable, hash-chained audit event. The audit API is read-only — you can list and export events but never mutate them.

Webhooks

Register HTTPS endpoints to receive signed, retried event notifications. Each endpoint has its own signing secret used to compute the X-Merlon-Signature header.