API Reference
Nexus exposes a REST API via Supabase Edge Functions, the Supabase auto-generated PostgREST API, and a hosted MCP endpoint for AI agents. This section covers authentication, conventions, AI-agent access, the social/content-calendar MCP surface, and the public OpenAPI specification.
In this section
- Authentication — human JWTs, agent JWTs, and API-key exchange flow.
- AI Agents, API Keys, and MCP — hosted MCP endpoint, tool list, social/content-calendar tools, resources, and agent workflow.
- Rate Limiting & Pagination — request limits and result pagination.
- OpenAPI Specification — interactive spec and download link.
API base URLs
| Service | Base URL | Description |
|---|---|---|
| Edge Functions | https://<project-ref>.supabase.co/functions/v1/ | Custom serverless endpoints |
| PostgREST | https://<project-ref>.supabase.co/rest/v1/ | Auto-generated CRUD from database |
| Auth | https://<project-ref>.supabase.co/auth/v1/ | Supabase Auth endpoints |
| Storage | https://<project-ref>.supabase.co/storage/v1/ | File uploads and downloads |
| MCP | https://<project-ref>.supabase.co/functions/v1/mcp-server | Hosted MCP Streamable HTTP endpoint |
Replace <project-ref> with your Supabase project reference. Exact URLs are provided during onboarding and are not published publicly.
Security model
All API requests require a valid bearer token unless explicitly documented as public. Nexus uses three credential classes:
- User JWT — issued by Supabase Auth after login. Used by human users and admin tooling.
- Agent JWT — short-lived bearer token issued by
agent-authafter exchanging an agent API key. - Service Role Key — privileged server-to-server credential. Never exposed to clients or public documentation.
Agent API keys are not used directly against business endpoints. They are exchanged for agent JWTs first.
Every write endpoint is explicitly marked "Auth Required" in the specification. Read endpoints also require authentication unless explicitly marked as public (e.g., webhook receivers with verify-token validation).
Endpoint tags
The OpenAPI specification organizes endpoints into these tags:
| Tag | Description |
|---|---|
Auth | Authentication and session management |
Contacts | Contact (customer) CRUD and search |
Messages | Send and receive messages across channels |
Orders | Order management and lifecycle |
Inventory | Stock, warehouse, and bin operations |
Shipping | AWB creation, tracking, labels |
VoIP | Call initiation, CDR, extensions |
AI | AI annotation, insights, embeddings |
Automation | Workflow rules and execution |
Integrations | Integration setup and sync |
Agents | API-key exchange, MCP access, and agent integrations |