API reference

The Ownrecord REST API: conventions, every operation, error codes and event types, generated from the operation registry.

Every capability of Ownrecord is one operation. Each operation is available in the console, as a REST endpoint and as a tool of the MCP server, with the same input, permission, risk tier and audit trail. This reference is generated from the operation registry, so it always matches the API.

Base URL and authentication

All endpoints live under https://ownrecord.io/api/v1 and speak JSON only. Authenticate with an API key in the Authorization header: Authorization: Bearer or_test_…. The key decides where a call acts: a brand key acts on its brand, an entity key on its legal entity and its brands, an organization key on the whole organization. It also decides the mode: test keys see test data only, live keys live data only. An organization or entity key that calls a brand or entity operation names its target with Ownrecord-Brand: brd_… or Ownrecord-Entity: ent_…. A target outside the key's reach answers resource_not_found.

Versions

The current version is 2026-10-01. Send Ownrecord-Version: 2026-10-01 to pin it per request; without the header, your account's pinned version answers. Every response says which version answered in its Ownrecord-Version header.

Requests

GET requests take their input in the query string; POST, PUT, PATCH and DELETE requests in a JSON body (Content-Type: application/json). Path parameters such as {id} are part of the input too. A field that repeats a path parameter with a different value is refused. Repeat a query parameter, or add [] to its name, to send a list: ?status=active&status=expired.

Responses

Responses are JSON. Resource fields use camelCase names, for example lookupKey; list and error envelopes use snake_case. Money is an object with integer micros (millionths of the currency's major unit) as a string and an ISO 4217 currency: { "amount": "12500000", "currency": "EUR" } is €12.50. Dates are ISO 8601 in UTC.

Every response carries an Ownrecord-Request-Id header. Quote it when you contact support.

Idempotency

Every POST needs an Idempotency-Key header, for example a UUID; PUT, PATCH and DELETE accept one. Retrying with the same key and the same request returns the first response without doing anything twice. The same key with a different request is refused with idempotency_key_reused. Keys are kept for 24 hours.

Dry runs

Send Ownrecord-Dry-Run: true to preview an operation that supports it: Ownrecord runs every check and computes the result and its effects, then rolls everything back. Nothing is saved or sent, and the response carries Ownrecord-Dry-Run: true. Dry-run every financial or compliance action first. When the real call would wait for a person's approval (your organization's approval policy, or an agent's or app's amount limits), the dry run still answers with the result and adds Ownrecord-Approval-Required: true: the real call will answer HTTP 202 with an approval request instead of running.

Lists and pagination

List operations return { "object": "list", "data": [...], "has_more": true, "next_cursor": "…" }, newest first. Ask for up to 100 items with limit, and for the next page with starting_after set to the previous page's next_cursor.

Errors

Errors return an HTTP status and a body like this one:

{
  "error": {
    "type": "invalid_request",
    "code": "validation_failed",
    "message": "The request is invalid.",
    "param": "name",
    "remediation": "Fix the fields listed in `details.issues` and send the request again.",
    "docs_url": "https://ownrecord.io/docs/reference/errors#validation_failed",
    "retryable": false,
    "request_id": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
    "details": {
      "issues": [
        {
          "path": "name",
          "message": "Too small",
          "code": "too_small"
        }
      ]
    }
  }
}

code is stable and listed in the error codes; remediation says what to do next, and retryable whether the same request can succeed later.

Common errors

Any operation can return these, depending on how it is called:

Rate limits

Each API key may make a number of requests per second set by your plan. Public endpoints that need no key are limited per IP address. Over the limit, the API answers 429 with rate_limited: wait for retry_after_ms (or the Retry-After header, in seconds), then retry with backoff.

Machine-readable

The OpenAPI 3.1 document of the API is at /api/v1/openapi.json. Each operation's operationId is its operation ID, and x-ownrecord-* fields give its scope, permission, risk tier and MCP tool.

Operations

Agents

Alert settings

Alerts

Announcements

API keys

App installations

Approval policies

Approvals

Apps

Assistant

Audit log

Authorizations

Bank statements

Brands

Checkout

Compliance

Coupons

Credit grants

Credit notes

Customers

Discounts

Disputes

Einvoice

Einvoices

Email preferences

Entities

Entitlements

Events

Exports

Features

Filing periods

Invitations

Invoice items

Invoices

Knowledge

Leads

Leases

Ledger

Legal

Members

OAuth connections

Onboarding

Organizations

Ownership transfers

Partner terms

Payment methods

Platform billing

Platform

Portal

Prices

Processor connections

Product updates

Products

Promotion codes

Reconciliation

Refunds

Registrations

Request logs

Reservations

Risk

Subscriptions

Support access

Tasks

Tax

Test clocks

Usage events

Usage

Users

Waitlist

Wallets

Webhook deliveries

Webhook endpoints