API Reference

All API requests are routed through the gateway at api.crowai.dev (prod) or dev.api.crowai.dev (dev). Requests require either a session cookie or an API key (crow_...). The gateway injects X-Organization-Id and Authorization: Bearer <JWT> headers before forwarding to internal services.

Base URL: https://api.crowai.dev/api/v1

Authentication

Session Cookie

Include the better-auth.session_token cookie (set automatically by the auth client on .crowai.dev). The gateway validates the session and retrieves a JWT.

API Key

Pass the key in one of these headers:

• X-API-Key: crow_...
• Authorization: Bearer crow_...
• ApiKey: crow_...

The gateway resolves the organization from the key owner's user record.

Auth Service

Sign Up

POST /api/v1/auth/sign-up/email

Body:

{
  "name": "string",
  "email": "string (business domain only)",
  "password": "string"
}

Consumer email domains (gmail.com, yahoo.com, outlook.com, hotmail.com, etc.) are rejected.

Sign In

POST /api/v1/auth/sign-in/email

Body:

{
  "email": "string",
  "password": "string"
}

Get Session

GET /api/v1/auth/get-session

Returns the current session including activeOrganizationId.

Get JWT

GET /api/v1/auth/token

Returns a signed JWT for the authenticated session. Used internally by the gateway.

JWKS

GET /api/v1/auth/jwks

Public endpoint. Returns the JSON Web Key Set for JWT verification.

Create Organization

POST /api/v1/auth/organization/create

Body:

{
  "name": "string",
  "slug": "string"
}

Triggers sync to org service and user service.

Set Active Organization

POST /api/v1/auth/organization/set-active

Body:

{
  "organizationId": "string (Better Auth org ID)"
}

Create API Key

POST /api/v1/auth/api-key/create

Returns a crow_-prefixed API key.

Verify API Key (Internal)

POST /api/v1/auth/api-key/verify

Requires X-Service-API-Key header. Returns key metadata including userId.

---

Users

Get Current User

GET /api/v1/users/me

Get User by ID

GET /api/v1/users/{id}

Get User Permissions

GET /api/v1/users/{id}/permissions

Response:

{
  "chat": { "enabled": true, "components": [], "lookbackWindow": 30 },
  "interactions": { "enabled": true },
  "patterns": { "enabled": true },
  "teamManagement": { "enabled": true },
  "apiKeyManagement": { "enabled": true }
}

List Users in Organization

GET /api/v1/users/by-organization/{organizationId}

Search Users by Email

GET /api/v1/users/search-email?q={prefix}

Update Profile

PATCH /api/v1/users/{id}/profile

Body:

{
  "name": "string",
  "profilePictureUrl": "string"
}

Upload Profile Picture

POST /api/v1/users/{id}/profile-picture

Multipart form data with image file. Stored in R2.

---

Organizations

Get Organization

GET /api/v1/organizations/{id}

Get Organization Members

GET /api/v1/organizations/{id}/members

Get Organization Context

GET /api/v1/organizations/{id}/context

Returns the latest AI-generated organizational context summary.

Trigger Context Generation

POST /api/v1/organizations/{id}/context/trigger

Enqueues an async context generation job.

Invite Member

POST /api/v1/organizations/{organizationId}/members

Body:

{
  "email": "string",
  "role": "member | admin"
}

---

Products

Create Crawler Job

POST /api/v1/products/crawler-jobs

Body:

{
  "sourceType": "url",
  "sourceValue": "https://example.com/products"
}

SSRF protection blocks private IPs, loopback, link-local, and internal CROW hostnames.

Get Crawler Job

GET /api/v1/products/crawler-jobs/{id}

List Crawler Jobs

GET /api/v1/products/crawler-jobs/organization/{orgId}

List Products

GET /api/v1/products/organization/{orgId}

Query params: page, limit

Get Product

GET /api/v1/products/{id}

Search Products

GET /api/v1/products/search?q={query}&type={semantic|fts|hybrid}

Param	Description
q	Search query
type	semantic (Vectorize), fts (full-text), hybrid (both)

Get Product Image (Public)

GET /api/v1/products/images/{key}

No authentication required. Serves images from R2.

Get AI Descriptions

GET /api/v1/products/{id}/ai-descriptions

Returns vision model-generated image captions and extracted features.

---

Interactions

List Interactions

GET /api/v1/interactions/organization/{orgId}

Query params: page, limit, sourceType (web, cctv, social), q (search)

Get Interaction Summary

GET /api/v1/interactions/organization/{orgId}/summary

Response:

{
  "web": 150,
  "cctv": 42,
  "social": 18,
  "total": 210
}

Analyze Interactions

POST /api/v1/interactions/organization/{orgId}/analyze

AI-generated analysis including summary, insights, anomalies, and recommendations. Uses Workers Container for longer processing.

---

Patterns

List Pattern Results

GET /api/v1/patterns/results/organization/{orgId}

Query params: period (daily, weekly, monthly, yearly)

List Patterns

GET /api/v1/patterns/organization/{orgId}

Trigger Analysis

POST /api/v1/patterns/analyze

Ad-hoc pattern analysis for the caller's organization.

---

Chat

Create Session

POST /api/v1/chat/sessions

Send Message

POST /api/v1/chat/messages

Body:

{
  "sessionId": "string",
  "content": "string"
}

Response is streamed. The AI agent may call tools (search_products, get_interactions, get_patterns) before generating a response.

Get Message History

GET /api/v1/chat/history?sessionId={id}

List Sessions

GET /api/v1/chat/sessions

Delete Session

DELETE /api/v1/chat/sessions/{id}

---

Q&A

Ask a Question

POST /api/v1/qna/query

Body:

{
  "question": "string",
  "history": [
    { "role": "user", "content": "string" },
    { "role": "assistant", "content": "string" }
  ]
}

RAG-based answer generation using Vectorize document retrieval and Workers AI.

---

Billing

Get Plans

GET /api/v1/billing/plans

Create Checkout Session

POST /api/v1/billing/checkout/session

Body:

{
  "builderId": "string"
}

Returns a Stripe checkout URL.

Get Subscription

GET /api/v1/billing/subscriptions/{organizationId}

Stripe Webhook

POST /api/v1/billing/webhook

Public endpoint (no auth). Stripe signature verification via Stripe-Signature header. Handles checkout.session.completed, checkout.session.expired, and payment_intent.payment_failed events.

---

Analytics

Create Event

POST /api/v1/analytics/events

Body:

{
  "event_type": "string",
  "source": "string",
  "metadata": {}
}

List Events

GET /api/v1/analytics/events

Query params: page, limit

Get Summary

GET /api/v1/analytics/summary

Aggregated event counts by type.

---

Notifications

Send Email

POST /api/v1/notifications/send

Body:

{
  "to": "string",
  "template": "string",
  "data": {}
}

---

CCTV

Submit Frame

POST /api/v1/cctv/frames

Body: Multipart with base64-encoded frame image.

Create Session

POST /api/v1/cctv/sessions

WebSocket Connection

GET /api/v1/cctv/ws

Upgrade to WebSocket for real-time frame streaming via Durable Object.

List Cameras

GET /api/v1/cctv/cameras/{orgId}

List Sessions

GET /api/v1/cctv/sessions

Get Session Results

GET /api/v1/cctv/sessions/{id}/results

---

MCP

MCP Protocol Endpoint

POST /api/v1/mcp
GET /api/v1/mcp

Implements the Model Context Protocol JSON-RPC specification. Authenticated via API key. Available tools: query interactions, query patterns, search products.

---

Error Responses

All services return errors in a consistent format:

{
  "error": "Error message"
}

Status	Meaning
400	Invalid request parameters
401	Unauthorized (missing or invalid auth)
403	Forbidden (BOLA check failed)
404	Resource not found
429	Rate limited
500	Internal server error

Validation errors (Zod) are sanitized to "Invalid request parameters" without leaking schema details.

Rate Limiting

The gateway applies per-IP rate limiting:

• Standard routes: Default rate limit
• Auth routes: Stricter limit (sign-in, sign-up, API key verification)

Health Checks

All services expose health endpoints that bypass authentication:

GET /api/v1/{service}/health
GET /api/v1/{service}/ready