Home Getting Started Open API spec (v0 draft)

Open API spec (v0 draft)

Last updated on May 16, 2026

Open API spec (v0 draft)

OpenAPI 3.1, published and versioned. The machine-readable description of every OrangeRails endpoint, request shape, response shape, and error code.

Status: v0 draft

We're pre-1.0. The schema is generated from the edge function code but not yet committed to additive-only changes. Breaking changes can happen between v0 and v1. Track the version field at the top of the spec.

At 1.0 (Phase 3 on the roadmap), the schema freezes: additive changes only after that. SDK + client generation become safe.

Where to find it

  • OpenAPI 3.1 YAML — github.com/MorningRevolution/orangerails/blob/dev/docs/openapi.yaml (TBD — will land in Phase 1 once the spec generator is wired in CI)
  • Interactive playground — docs.orangerails.com/openapi (planned for Phase 4 when the dedicated dev portal lands)
  • Today: the API reference is the human-readable version, kept in sync by hand

What it covers

The spec enumerates every endpoint under /functions/v1/*, both the public catalog and the platform/direct-auth endpoints:

  • or-providers — public catalog of source adapters + categories
  • or-platform-display — platform display info for the Connect widget
  • or-provision — create or fetch a subaccount for a platform user
  • or-connection-create, or-connection-list, or-connection-delete — connection lifecycle
  • or-discover-wallets, or-source-wallets-set — wallet selection inside a connection
  • or-sync, or-transactions-list — fetch + read normalized transactions
  • or-stealth-connection-create, -list, -delete, or-stealth-envelope-fetch, or-stealth-transactions-store — Stealth Sync sealed envelope endpoints

Each operation declares its request body schema, response schema, error codes, rate limit headers, and auth requirements.

Schemas worth knowing

ProviderManifest

type: object
required: [slug, displayName, status, multiWallet, credentialFields]
properties:
  slug: { type: string }
  displayName: { type: string }
  description: { type: string }
  status: { type: string, enum: [live, beta, coming_soon] }
  category: { type: string, enum: [lightning_wallet, on_chain_wallet, payment_processor, exchange, card, mining, bank, lender] }
  tags: { type: array, items: { type: string } }
  popularity: { type: integer }
  multiWallet: { type: boolean }
  credentialFields:
    type: array
    items:
      type: object
      required: [name, type, label]
      properties:
        name: { type: string }
        type: { type: string, enum: [string, secret] }
        label: { type: string }
        placeholder: { type: string }

NormalizedTransaction

type: object
required: [id, adapter, direction, type, timestamp]
properties:
  id: { type: string, description: "Provider-side stable id (dedup key)" }
  external_id: { type: string }
  adapter: { type: string }
  direction: { type: string, enum: [in, out] }
  type: { type: string, enum: [lightning, onchain, trade, deposit, withdrawal, fee] }
  amount_sats: { type: integer }
  amount: { type: number }
  currency: { type: string }
  description: { type: string, nullable: true }
  counterparty: { type: string, nullable: true }
  status: { type: string }
  timestamp: { type: string, format: date-time }
  external_payload: { type: object, additionalProperties: true }

Error envelope

type: object
required: [error, message]
properties:
  error: { type: string, description: "Machine-readable code (e.g. INVALID_PLATFORM_KEY)" }
  message: { type: string, description: "Human-readable description" }

Versioning policy (post-1.0)

  • MAJOR.MINOR.PATCH in the spec info.version field.
  • MAJOR bump = breaking change. Only allowed in a deprecation cycle: announce in newsletter + GitHub release, ship v(N) alongside v(N+1) for 90 days, then sunset.
  • MINOR bump = additive (new endpoint, new optional field, new enum value).
  • PATCH bump = doc-only.

A v1 endpoint will be served under /functions/v1/*. When v2 ships, it lives at /functions/v2/* and v1 keeps working for the deprecation window.

Generators + tooling

These will be officially blessed once the spec lands:

  • TypeScript SDK — auto-generated from the spec, published as @orangerails/sdk (planned Phase 1)
  • Postman collection — exported from the spec, committed under docs/postman.json
  • MCP-compatible tool definitions — derived from the same spec so AI assistants can call the API with full type safety (Phase 3 — MCP-1.0 spec lock)

What's NOT in the spec

  • The Stealth Sync postMessage protocol — that's a browser-to-widget contract, not an HTTP API. Documented separately in src/stealth/lib/postmessage.ts and on the Stealth Sync wiki page.
  • Internal admin endpoints (/admin/*, /portal/*) — not part of the public surface.
  • The encryption details (which fields are sealed where) — those live in the Security and threat model doc, because they're architectural, not API-surface.

See also