REST API and OpenAPI

Use the published contract

Yanola publishes the complete Developer Platform REST contract as OpenAPI 3.1 JSON. It is the machine-readable source for paths, parameters, request and response schemas, authentication, examples, headers, and public error responses.

The checked-in artifact is served with the documentation site and is copied byte-for-byte from the backend source contract. Download it for local inspection, validation, mock generation, or client tooling.

• View OpenAPI 3.1 JSONOpen the published, machine-readable REST /v1 contract in your browser.
• Download OpenAPI 3.1 JSONSave the exact contract used by backend and SDK contract verification.
• Use the Node.js SDKPrefer the hand-written @yanola/whatsapp client when building a server-side Node.js integration.

Stable REST /v1 and webhook compatibility

REST /v1 will not remove or rename documented endpoints or fields, make optional request fields required, change documented field types incompatibly, reuse stable error codes with different meanings, or change accepted behavior incompatibly. A breaking protocol change requires a new major API base path.

Compatible evolution can add endpoints, optional capabilities, optional response fields, distinguishable error codes, explicitly subscribed webhook event types, and fields inside extensible normalized event data. Ignore unknown response and webhook fields. A deprecated /v1 operation remains part of /v1 even after its replacement is documented.

Make an authenticated REST request

Send every request to the production /v1 base URL over HTTPS. Put one Yanola API Key in the Authorization header using the Bearer scheme and keep that key in server-side environment configuration.

The key resolves the Yanola Account, Agent Project, environment, scopes, and optional Sender restrictions. A Test Mode key cannot read or mutate Live Mode data, and a Live Mode key cannot access Test Mode data.

curl --request POST \
  --url https://api.yanola.ai/v1/messages/text \
  --header "Authorization: Bearer $YANOLA_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: send-order-123" \
  --data '{
    "from": "+15557654321",
    "to": "+15551234567",
    "body": "Hello from Yanola",
    "previewUrl": false
  }'

Published request and response examples

These JSON blocks are exact copies of named examples in the published OpenAPI document. The SDK contract test parses the same component examples and validates them against their assigned OpenAPI schemas before exercising the backend routes.

{
  "from": "+15557654321",
  "to": "+15551234567",
  "body": "Legacy phone clients can migrate the base path first.",
  "previewUrl": false
}

{
  "id": "msg_0123456789ABCDEabcdeWXYZ",
  "environment": "live",
  "status": "queued",
  "from": "+15557654321",
  "to": "+15551234567",
  "requestId": "req_0123456789",
  "createdAt": "2026-07-21T12:00:00.000Z"
}

Message operations

Catalog and media operations

Event, delivery, and usage operations

Use idempotency for safe mutations

Send an Idempotency-Key when your application may retry a send, mark-read, or delivery-replay request. The value must be 8 through 255 characters.

Yanola scopes the key by Agent Project, environment, concrete endpoint, API key, and request-body hash. Repeating the same operation with the same body returns the original outcome; reusing the key with a different body returns 409 idempotency_key_reused.

1. Generate one stable key for one logical mutation, such as an order notification.
2. Persist the key with your job or outbox record before the first network attempt.
3. Reuse it only when retrying the identical endpoint and body.
4. Create a new key when the intended mutation or body changes.

Paginate and filter list operations

List endpoints use opaque cursor pagination. Omit limit for the default of 20, or request 1 through 100 items. When pagination.hasMore is true, pass pagination.nextCursor unchanged as the next cursor.

Filters are endpoint-specific. Common filters include environment, from, status, created_after, and created_before. Date filters use RFC 3339 date-time strings. Do not parse, construct, or reuse a cursor with a different filter set.

curl --get "https://api.yanola.ai/v1/messages" \
  --header "Authorization: Bearer $YANOLA_API_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "environment=live" \
  --data-urlencode "cursor=$YANOLA_NEXT_CURSOR"

Distinguish protocol and account limits

Fixed request-shape limits are part of the GA protocol. Commercial capacity is account-specific and must be discovered from the current subscription entitlement and live response headers; development seed tiers are not a public price or limit promise.

Read response and rate-limit headers

Handle the public error envelope

Every documented JSON error response uses one stable envelope. Branch on error.code for program behavior, use retryable and HTTP status to decide retry policy, and retain requestId for support correlation.

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after the time in the retry-after header.",
    "requestId": "req_0123456789",
    "retryable": true,
    "details": {}
  }
}

Understand example coverage

Every named component example has one declared contract schema. The SDK contract test fails when an example is added without a mapping, when a mapped example violates its schema, or when a real backend response violates the operation response schema.

Generate clients carefully

Use tooling that supports OpenAPI 3.1 and JSON Schema 2020-12 semantics. Resolve local component references, preserve string formats and regex constraints, and validate generated request types before trusting generated code.

Generated clients do not replace operational behavior. Keep API keys server-side, preserve idempotency keys across retries, honor retry-after, accept additive response fields, and follow asynchronous message state through logs or events.

Verify the contract locally

The canonical JSON lives in the backend project. The frontend sync command republishes it byte-for-byte, the frontend check rejects drift, the backend suite verifies REST invariants and local references, and the SDK suite validates every example plus real route responses.

cd yanola.ai
npm run openapi:sync

cd yanola.ai
npm run openapi:check
npm run test:developer-platform -- --runTestsByPath src/app/docs/docs-structure.spec.tsx

cd ../yanola.ai.be
npx jest src/developer-platform/openapi/openapi-v1.spec.ts --config ./jest.config.cjs --runInBand

cd ../yanola.whatsapp
npm run test:contract