API Reference
Use this page when you need the HTTP surface: integration rules and the generated OpenAPI contract in one place.
Overview
This page is the stable entry point for developers. It keeps the human-readable integration basics close to the generated OpenAPI spec so prose and machine-readable contract stay aligned.
If you are reading the schema before the setup guide, keep the Glossary nearby for terms such as approval, request, Memory item, and trust rule.
Current embedded schema:
MagicPay API 1.1.0 using OpenAPI 3.1.0.
Base URL
All public API routes are served from the production MagicPay API base URL, `https://agents-api.mercuryo.io/functions/v1/api`.
| Field | Value |
|---|---|
| Host | https://agents-api.mercuryo.io |
| Base path | /functions/v1/api |
| Base URL | https://agents-api.mercuryo.io/functions/v1/api |
Authentication
Authenticated routes require a bearer API key. Public routes are intentionally limited to health and schema discovery surfaces.
Authorization: Bearer <api_key>
Public routes stay intentionally narrow: GET /health and GET /openapi.json.
Key Scopes
API keys are either agent-scoped or user-scoped. Agent-scoped keys are narrower and should be used whenever the workflow belongs to one concrete agent.
Scope Use it when Main limitations Agent-scoped The workflow belongs to one concrete agent. Prefer this for protected sessions and agent identity routes. User-scoped You need broader read access across user-owned workflow data. Do not assume agent-only routes are available.
Route Groups
The public surface is organized around health, agent identity, workflow sessions, observability, LLM compatibility, and tooling support such as CAPTCHA.
Group What it covers Health Basic liveness and discovery routes. Agent Authenticated agent identity and stats. Sessions Workflow-session creation, events, request lifecycle, request artifacts, and Memory-aware resolution. Observability Trace ingestion for workflow observability. LLM and tools Compatibility and supporting tool routes such as CAPTCHA tasks.
Schema
The embedded OpenAPI section below is the automatically updated reference. Use it for exact request and response fields, and use the JSON schema route when you need the machine-readable contract directly.
Machine-readable schema:
/docs/openapi.json