API Overview

The Reeve Services API is the backend that powers connectors, analytics, billing, and brand intelligence. It sits between the Reeve gateway (where agents run) and external platforms (Shopify, Stripe, Meta, etc.).

What the API Does

Architecture

Cockpit (Frontend)
    │
    ├── /api/connectors/*  ──▶  Services API
    ├── /api/brand/*       ──▶      │
    ├── /api/dashboard/*   ──▶      ├── PostgreSQL
    ├── /api/credits/*     ──▶      ├── External APIs
    └── /api/auth/*        ──▶      └── Stripe

Gateway (Agent Runtime)
    │
    └── /api/credits/deduct ──▶  Services API

Authentication

The API uses two authentication methods depending on who's calling:

User Requests (Frontend → API)

All user-facing requests use a session token from the Cockpit:

Authorization: Bearer <session-token>

Session tokens are managed by Clerk and are included automatically when you use the Cockpit. They expire and refresh transparently.

Service Requests (Gateway → API)

The gateway communicates with the Services API using a shared service token:

X-Reeve-Services-Token: <shared-secret>

This is used for operations like credit deductions during agent sessions. You don't need to configure this manually — it's set up during deployment.

Base URL

All endpoints are prefixed with /api/. For example, the connectors list endpoint is GET /api/connectors/list.

Rate Limits

The API applies rate limiting per user to prevent abuse:

Rate-limited responses return 429 Too Many Requests with a Retry-After header.

How Agents Use the API

Agents don't call the Services API directly. Instead, they use specialized tools that resolve credentials through the gateway:

// Agent uses a tool → gateway resolves credentials → calls Services API
reeve_shopify({ action: "get_overview" })
reeve_ads({ action: "get_performance", platform: "meta" })
reeve_email({ action: "list_campaigns" })
reeve_analytics({ action: "get_summary", period: "30d" })

The gateway handles token resolution, refresh, and error handling. Agents never see raw API keys or OAuth tokens.

Error Handling

The API returns standard HTTP status codes:

Error responses include a JSON body with details:

{
  "error": "connector_not_found",
  "message": "No Shopify connector found for this account",
  "status": 404
}

Data Privacy

• Live fetching — Data is fetched from external APIs in real time, not cached or stored
• Encrypted credentials — OAuth tokens and API keys are encrypted at rest
• Scoped access — Each user's connectors are isolated; no cross-account data access
• Token refresh — OAuth tokens are refreshed automatically before expiry