Fortune OS

Fortune OS developer documentation

Fortune OS exposes its business data to programs through a Model Context Protocol server and versioned REST endpoints on the same origin as the application. Access is self-serve: any merchant mints keys for their own businesses, and no credential grants more than the account already holds.

Getting access

  • Create an account and add a business; the 30-day trial starts from the catalog and needs no sales contact.
  • Open Settings → Profile → MCP tokens and create a key. Keys are prefixed `fos_`, shown once, scoped to one business or to every business you can access, read-only unless you grant catalog availability writes, and expire after 90 days by default.
  • An MCP connector such as Claude can instead sign in through OAuth; the authorization server metadata describes that flow.

Authentication

The MCP server takes a bearer credential on every request: `Authorization: Bearer fos_…` for an API key, or the OAuth access token a connector obtained. A missing or invalid bearer answers `401` with a `WWW-Authenticate` challenge whose `resource_metadata` points at the protected-resource document. Browser-bound REST endpoints such as report exports authenticate with the signed-in session cookie. Every call resolves the live account, memberships and permissions again, so a revoked key or removed membership stops access on the next request.

MCP server

Endpoint: `POST /api/mcp/v1`, streamable HTTP with JSON responses, stateless per request. The manifest names the endpoint, transport and authorization server. Tools: `business_context` (reachable organizations, venues and permissions), `describe_business_data` (dataset definitions), `query_sales` (aggregates by date, hour, weekday, venue, order type, channel or item), `read_business_records` (orders, items, payments and events), `read_merchant_data` (every modeled merchant dataset with explicit projections), `read_catalog`, and `set_catalog_availability` for credentials with a write grant. `tools/list` is the generated contract: each tool publishes its input and output schema and read-only or idempotent annotations.

curl -s https://app.fortuneos.ai/api/mcp/v1 \
  -H "Authorization: Bearer fos_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
curl -s https://app.fortuneos.ai/api/mcp/v1 \
  -H "Authorization: Bearer fos_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"business_context","arguments":{}}}'

A successful tool call returns `structuredContent` shaped as `{ "result": … }` and the same JSON as text. A failed call sets `isError: true` and returns `{ "error": { "code": …, "message": … } }`, where `FORBIDDEN` means denied authority and `CONFLICT` means stale expected state.

REST endpoints

The OpenAPI 3.1 document is generated at startup from the Zod schemas that validate each request and lists every public operation with a unique `operationId`, typed parameters and response schemas. Surfaces are versioned in the path and a breaking change ships as a sibling version; an unknown version answers `404`. Report exports: `GET /api/exports/v1/{report}/{format}` downloads a CSV or PDF report for an authorized venue scope. MyFatoorah documents: `POST /api/myfatoorah-documents/v1/upload` uploads a KYC document for a connected gateway. Inbound webhooks under `/webhooks/v1` are HMAC-signed and their contract is served to signed-in sessions only.

Errors and rate limits

  • Every API error is JSON: `{ "error": "<code>" }` on the MCP and webhook surfaces, `{ "message": "<explanation>" }` on report exports, and `{ "error": "not_found", "message": …, "hints": … }` for an unknown `/api` path.
  • `401` carries a `WWW-Authenticate` challenge; `403` means the credential is valid but not authorized for that business, venue or field; `405` names the allowed method; `409` means an expected state no longer holds; `413` means a body or an export is too large; `504` means the database deadline was reached and the scope must be narrowed.
  • Requests are rate limited per client address in a 15-minute window and answered with the draft-7 `RateLimit` headers; `429` includes `Retry-After`.

Discovery files