AI Agents Overview

Give an AutoRev API key to your AI agent (Claude, GPT, Gemini, LangChain, Cursor, a custom agent, whatever you're using). The agent can then provision receptionists, place outbound calls, send SMS, and read call history on the tenant's behalf, bounded by the scopes on the key.

Step 1: Paste this system prompt into your agent

You are an operations assistant for the AutoRev account associated with the API key you have been given. AutoRev is an AI voice receptionist platform for service businesses.

At session start:
- GET https://app.autorev.ai/api/v1/account to learn the plan and usage.
- GET https://app.autorev.ai/api/v1/receptionists to discover what receptionists exist.
- GET https://app.autorev.ai/api/v1/tools/manifest to learn exactly which tools your key can invoke.

Rules of engagement:
- Authenticate every request with the header: Authorization: Bearer <API_KEY>
- On every POST (calls, SMS, receptionist creation), send an Idempotency-Key header with a fresh UUIDv4. Only 2xx responses are cached for replay, so retrying the same key after fixing a 4xx is safe.
- On 4xx errors, read the "suggestion" field in the JSON body. It tells you how to fix the request without bothering the human.
- On 429, wait Retry-After seconds and resume.
- TCPA: do not text or call anyone who has no prior relationship with this tenant. Direct REST does not block this, so you must gate it yourself. Opt-outs (STOP) cannot be overridden; a 422 on POST /api/v1/.../sms means skip that contact.
- Full reference: https://app.autorev.ai/llms-full.txt
- OpenAPI spec: https://app.autorev.ai/api/openapi.json

Machine-readable discovery

AutoRev publishes agent-discovery files following the llmstxt.org convention:

URL	What it is
https://app.autorev.ai/llms.txt	Short discovery index (under 5KB): what the API is, core concepts, safety defaults, and where the authoritative references live
https://app.autorev.ai/llms-full.txt	Full prose reference (under 50KB): every endpoint, every scope, recipes, error handling. Generated from the live OpenAPI spec and tool manifest, safe to consume verbatim
https://app.autorev.ai/api/openapi.json	OpenAPI 3.1 spec with complete endpoint schemas for every v1 route
https://app.autorev.ai/api/v1/tools/manifest	Tool definitions filtered by the calling key's scopes (see Tool Manifest)
https://app.autorev.ai/api/mcp	MCP server endpoint (see MCP Server)

Point your agent at /llms.txt first; it links to everything else.

Scopes bound what the agent can do

Every API key carries a scopes array that limits which tools the key can invoke, and the server enforces scopes on every call. Scope values: read, send_sms, make_call, book, write_crm, admin (plus the legacy * wildcard).

Keys created from the dashboard currently carry the scopes ["read", "send_sms", "book"]; per-key scope selection is not yet self-serve, so treat any key you hand to an agent as able to send SMS and book. Contact support@autorev.ai if you need a restricted (for example, read-only) key. Create and revoke keys at Settings > Integrations.

A key with only the read scope cannot send SMS or place calls even if the agent tries; enforcement is server-side. Tools the key cannot invoke are filtered out of the tool manifest, and calling one anyway returns a 403 with a clear error.

Conventions agents should follow

Idempotency. Pass an Idempotency-Key header (a fresh UUIDv4) on every POST so retries never duplicate calls or SMS. AutoRev caches 2xx responses for 24 hours; a retry with the same key returns the cached response with an Idempotency-Replayed: true header. 4xx/5xx responses are not cached, so fixing a payload and retrying with the same key is safe.

The suggestion field. Every 4xx response returns JSON with an error message and an optional suggestion field, an imperative fix. An agent should always read suggestion before asking the user for help; it usually says exactly how to fix the request.

Rate limits. On 429, wait Retry-After seconds and resume. Do not hardcode limits; read X-RateLimit-Limit and X-RateLimit-Remaining from response headers at runtime.

TCPA rules for agents

These are hard rules, not suggestions:

• Opt-outs are enforced server-side and cannot be overridden. Sending SMS to a number that texted STOP returns 422. The agent must skip that contact.
• Direct REST does not block cold outbound. POST /api/v1/receptionists/:id/sms and POST /api/v1/receptionists/:id/calls do not check for a prior relationship. Your agent must gate cold outbound itself: do not text or call anyone who has no prior relationship with the tenant.
• The MCP/tool layer is stricter. Cold outbound via the MCP tool layer (POST /api/mcp) rejects numbers with no prior relationship. The REST layer leaves that responsibility with you.