# API Reference

Canonical URL: https://magiccard.ai/docs/api
Markdown URL: https://magiccard.ai/docs/api.md
Summary: Use this page when you need the HTTP API: integration rules and the generated OpenAPI contract in one place.
Description: Public MagicPay API reference with base URL, authentication rules, scope notes, and embedded OpenAPI.

## Canonical Answer

Use this page when you need the HTTP API: integration rules and the generated OpenAPI contract in one place. Public MagicPay API reference with base URL, authentication rules, scope notes, and embedded OpenAPI. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context.

## 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.

## Base URL

All public API routes are served from the production MagicPay API base URL, `https://durcottggsiesxxqzvbb.supabase.co/functions/v1/api`.

## Authentication

Authenticated routes require a bearer API key. Public routes are intentionally limited to health and schema discovery.

## 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.

## Route Groups

The public API is organized around health, agent identity, workflow sessions, observability, LLM compatibility, and tooling support such as CAPTCHA.

## 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.

## Related

- MagicPay SDK: https://magiccard.ai/docs/integrations/sdk
- Entities: https://magiccard.ai/docs/reference/entities
- Glossary: https://magiccard.ai/docs/glossary