Authentication & Conventions

Everything you need to know about authenticating requests and the conventions used across the API.

Base URL

All API requests are made to:

https://api.outreachagent.dev/v1

For local development, use http://localhost:4000/v1. The OpenAPI specification is available at api.outreachagent.dev/v1/openapi.json.

API Keys

All programmatic access uses API keys. Keys are prefixed with rm_ and scoped to an organization. Create keys in the console or via POST /v1/api-keys. The full key is returned once — OutreachAgent stores only a SHA-256 hash.

Authorization: Bearer rm_live_a1b2c3d4e5f6...

Rate Limiting

The API enforces 100 requests per minute per organization. When exceeded, the API returns 429 Too Many Requests. The SDK automatically retries with exponential backoff on 429 and other transient errors (408, 500, 502, 503, 504).

Pagination

All list endpoints accept limit (1–100, default 20) and offset (default 0) query parameters. Responses include pagination metadata:

{
  "items": [...],     // array of resources
  "total": 142,       // total count across all pages
  "limit": 20,        // requested page size
  "offset": 0         // current offset
}

Idempotency

POST /v1/messages/send and POST /v1/enrollments accept an Idempotency-Key header. If a request is retried with the same key, the API returns the original response instead of creating a duplicate.

curl -X POST https://api.outreachagent.dev/v1/messages/send \
  -H "Authorization: Bearer rm_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{ ... }'

Error Responses

All errors follow a consistent format with machine-readable codes:

{
  "error": {
    "code": "validation_error",
    "message": "Field 'subject' is required"
  }
}