OpenAPI overview

The Lynx OpenAPI is the language-independent integration surface for recording agent runs, loading runtime configuration, reporting issue candidates, and reading run timelines.

Lynx is currently in pilot. To join the pilot or build an integration against the OpenAPI, contact partners@hvnn.me.

Use the official TypeScript SDK when it fits your application. Use the OpenAPI directly when you are building another language SDK, integrating an unsupported runtime, or need control over delivery and local storage.

Base URL and authentication

All public endpoints use this prefix:

https://api.lynxops.co/openapi/v1

Self-hosted installations replace the origin and keep /openapi/v1. The machine-readable OpenAPI 3.0 document is available without authentication at https://api.lynxops.co/openapi.json. See OpenAPI schema for code generation guidance. Send the workspace API key in every request:

X-API-Key: YOUR_WORKSPACE_API_KEY
Content-Type: application/json

Do not use an end-user Bearer token. The API key selects the workspace and environment, so request bodies cannot override that tenant boundary.

Endpoints

Method	Path	Required scope	Purpose
`POST`	`/events/batch`	`events:write`	Record up to 100 events.
`POST`	`/issue-records`	`events:write`	Submit a detection or recovery record for asynchronous review.
`GET`	`/runtime-config`	`config:read`, `policies:read`	Load current prompt versions and active policies.
`POST`	`/firewall-approvals`	`events:write`	Request approval for one protected tool call.
`GET`	`/firewall-approvals/{approvalId}`	`policies:read`	Poll the current approval status.
`GET`	`/runs`	`usage:read`	List runs with cursor pagination.
`GET`	`/runs/{runId}`	`usage:read`	Read one run and its first event page.
`GET`	`/runs/{runId}/events`	`usage:read`	Read the remaining event timeline.

Minimal request

curl --request POST \
  --url https://api.lynxops.co/openapi/v1/events/batch \
  --header "X-API-Key: $LYNX_API_KEY" \
  --header "Content-Type: application/json" \
  --data '[
    {
      "eventId": "evt_01JZQ3W8FQ",
      "clientId": "python-worker-01",
      "runId": "run_01JZQ3VY4K",
      "sessionId": "session_customer_42",
      "agentName": "support-agent",
      "eventType": "USER_INPUT",
      "label": "Customer message",
      "timestamp": 1784808000000,
      "payload": {
        "text": "I cannot sign in"
      }
    }
  ]'

Build another language SDK

A production integration should contain these components:

A run context that propagates runId, sessionId, spanId, and parentSpanId.
A bounded in-memory or durable queue.
A background batch sender with a short timeout.
Retry handling based on retryableEventIds.
Permanent removal of rejectedEventIds.
Stable eventId and clientRecordId values across retries.
A runtime configuration cache that uses ETag.
Local policy evaluation before a tool executes.
A bounded approval flow for REQUIRE_APPROVAL decisions.
flush and shutdown operations for graceful process exit.

Event delivery should fail open: a Lynx outage must not fail the customer request. A high-risk local policy may separately choose fail-closed behavior. For REQUIRE_APPROVAL, create one request with a stable clientRequestId, poll only until the configured deadline, and execute the protected tool only after an APPROVED response. Network failures, invalid responses, rejection, and expiration must not implicitly allow execution.

Common HTTP behavior

400 means the request does not match the public contract.
401 means X-API-Key is missing or invalid.
403 means the key does not have the required scope.
413 means the request body is too large.
429 means the rate limit was exceeded. Respect Retry-After.
5xx errors are temporary unless your application has stronger evidence.

Use exponential backoff with jitter for network errors, 429, and 5xx responses. Set a maximum queue size so an extended outage cannot consume unbounded memory.

Prompts, tool arguments, model responses, logs, and arbitrary payload fields may contain sensitive data. Mask secrets before enqueueing data, enforce a payload size limit locally, and never log the workspace API key.

Next steps

Download the OpenAPI schema

Generate an HTTP client from the public machine-readable contract.

Record events

Define the event envelope, batching, and retry behavior.

Load runtime config

Cache prompt versions and policies for local use.

Request firewall approval

Pause a protected tool call until an operator decides.

Report issue candidates

Submit detections without blocking agent execution.

Read runs

Inspect runs and page through their event timelines.

​Base URL and authentication

​Endpoints

​Minimal request

​Build another language SDK

​Common HTTP behavior

​Next steps

Download the OpenAPI schema

Record events

Load runtime config

Request firewall approval

Report issue candidates

Read runs

Base URL and authentication

Endpoints

Minimal request

Build another language SDK

Common HTTP behavior

Next steps