API Introduction

Base URLs

The REST API is mounted at:

https://api.onlucra.com/v1

The MCP server is mounted at:

https://api.onlucra.com/mcp

REST and MCP use the same managed API keys, exact scopes, workspace binding, queries, and supported mutations. Public operations run through Lucra's existing domain handlers, so tenant boundaries, delegated-access rules, validation, notifications, and review behavior remain consistent with the platform.

Response envelope

REST successes put the response under data:

{
  "data": { "programs": [] },
  "ok": true
}

Failures use a stable error envelope:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This token is missing required scopes."
  },
  "ok": false
}

All REST responses are JSON and use cache-control: no-store.

Machine-readable reference

The allowlisted REST surface is available as OpenAPI 3.1 at https://api.onlucra.com/v1/openapi.json. The specification is generated from the same route contracts used by the gateway.

For a runnable Postman setup, import https://api.onlucra.com/v1/postman-collection.json, set the collection's lucra_api_key variable, then run Start here and Safe reads. Optional query parameters are disabled, item requests wait for real ID variables, and mutations remain skipped until run_mutations is set to true.

When the Worker is running locally, import http://127.0.0.1:8787/v1/postman-collection.json instead. Its base_url is generated for the local Worker automatically.