Integration API

Overview

The CROW platform exposes a comprehensive Integration API Layer built on Cloudflare Workers, providing global low-latency access for both internal and external consumers. The API layer supports REST, MCP (Model Context Protocol), and Agent-to-Agent (A2A) protocols.

Architecture

API Types

CROW provides multiple API access methods optimized for different use cases.

1. REST API

Audience: Dashboard, external clients, mobile apps, web applications

Features:

Edge Deployment: Runs on Cloudflare Workers globally
Authentication: API key and session-based auth
Rate Limiting: Configurable per-key limits
Versioning: URL-based versioning (v1)
Documentation: OpenAPI/Swagger specs per service

Endpoint Categories:

Category	Base Path	Description
Auth	`/api/v1/auth/*`	Authentication, sessions, API key management
Organizations	`/api/v1/organizations/*`	Organization CRUD and management
Users	`/api/v1/users/*`	User profiles, preferences, profile pictures
Products	`/api/v1/products/*`	Product catalog, search, AI descriptions
Interactions	`/api/v1/interactions/*`	Interaction data, search, summary
Patterns	`/api/v1/patterns/*`	Pattern data and search
Billing	`/api/v1/billing/*`	Subscriptions, checkout, plans, invoices, portal
Notifications	`/api/v1/notifications/*`	User notifications
Chat	`/api/v1/chat/*`	Chat sessions and messages
QnA	`/api/v1/qna/*`	Semantic search and knowledge base
Crawler	`/api/v1/crawler-jobs`	Web scraping job management

Key Endpoints:

GET /api/v1/interactions/organization/:orgId - List interactions with pagination and source type filtering
GET /api/v1/interactions/organization/:orgId/summary - Channel breakdown (web, cctv, social, total)
GET /api/v1/interactions/organization/:orgId/search - Semantic search across interactions
GET /api/v1/patterns/organization/:orgId - List patterns with filtering
GET /api/v1/patterns/organization/:orgId/search - Semantic search across patterns
GET /api/v1/products/organization/:orgId - List products with pagination
GET /api/v1/products/search - Semantic product search
GET /api/v1/products/:id/ai-descriptions - AI-generated product descriptions
POST /api/v1/billing/checkout/session - Create Stripe checkout session
POST /api/v1/billing/portal-session - Create Stripe customer portal session
POST /api/v1/billing/subscriptions/:orgId/cancel - Cancel subscription
POST /api/v1/billing/subscriptions/:orgId/resume - Resume cancelled subscription

2. MCP Server (Model Context Protocol)

Audience: LLM applications (Claude Desktop, Cursor, Windsurf, other MCP-compatible clients)

Status: Working

Endpoint: https://mcp.crowai.dev/mcp

Protocol: MCP over Streamable HTTP (JSON-RPC 2.0)

Authentication: API key in Authorization: Bearer <key> or X-API-Key header. The server verifies the API key against the auth service and resolves the associated organization ID.

Server Info:

Name: crow-mcp-server
Version: 1.0.0

Available Tools (6):

Tool	Description	Parameters
`crow_search_products`	Search product catalog (semantic, FTS, or hybrid)	`query` (required), `mode` (semantic/fts/hybrid), `limit`
`crow_search_interactions`	Search customer interaction history	`query`, `sourceType` (web/cctv/social), `limit`, `page`
`crow_get_interaction_summary`	Get channel breakdown counts	(none)
`crow_search_patterns`	Search behavioral patterns	`query`, `period` (daily/weekly/monthly/yearly)
`crow_get_product_ai_descriptions`	Get AI descriptions for a product	`productId` (required)
`crow_search_org_context`	Search organization knowledge base via QnA	`query` (required), `limit`

Claude Desktop Configuration:

{
  "mcpServers": {
    "crow-analytics": {
      "url": "https://mcp.crowai.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-Organization-Id": "YOUR_ORG_ID"
      }
    }
  }
}

Implementation Details:

Built on Cloudflare Workers with Hono (OpenAPIHono)
Supports initialize, tools/list, and tools/call JSON-RPC methods
GET /mcp returns server info and tool listing
POST /mcp handles JSON-RPC tool execution
Organization ID resolved from API key via auth service lookup
Input validation: query max 512 chars, product ID alphanumeric pattern, source types and periods validated against allowlists
Tools call the REST API Gateway internally with both API key and internal gateway key

3. Agent-to-Agent (A2A) Protocol

Audience: Enterprise AI systems, agent frameworks, external AI agents

Status: Working

Endpoint: https://a2a.crowai.dev/a2a/jsonrpc

Agent Card (Discovery): https://a2a.crowai.dev/.well-known/agent-card.json

Protocol: Based on Google A2A protocol patterns

Authentication: API key via X-API-Key header or Authorization: Bearer <key>

Agent Card Details:

{
  "name": "CROW Analytics Agent",
  "description": "AI-powered retail analytics assistant with access to product catalog, customer interactions, and behavioral patterns",
  "version": "1.0.0",
  "provider": {
    "organization": "CROW AI",
    "url": "https://crowai.dev"
  },
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "stateTransitionHistory": false
  },
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "skills": [
    { "id": "product-search", "name": "Product Search" },
    { "id": "interaction-analysis", "name": "Interaction Analysis" },
    { "id": "pattern-insights", "name": "Pattern Insights" },
    { "id": "org-context", "name": "Organization Context" }
  ],
  "authentication": { "schemes": ["apiKey"] }
}

Task Execution:

POST /a2a/tasks/send - Send a task to the CROW agent
- Request body includes message.parts[0].text (the query) and metadata.organizationId
- Runs the same agentic AI loop as the chat system (runCrewAgenticLoop)
- Returns completed task with text artifacts and source references
GET /a2a/tasks/:taskId - Get task status (returns completed state)

Example Python Client:

from a2a_client import A2AClient

client = A2AClient(
    url="https://a2a.crowai.dev/a2a",
    api_key="YOUR_API_KEY"
)

response = client.send_task({
    "message": "What are our top performing products?",
    "organization_id": "YOUR_ORG_ID"
})

Implementation: The A2A endpoints are served by bff-chat-service on Cloudflare Workers. The service uses the same AI backend (Cloudflare Workers AI with @cf/meta/llama-3.3-70b-instruct-fp8-fast) and tool-calling loop as the dashboard chat.

4. GraphQL API (Optional/Future)

Status: Not currently implemented. Marked as optional for future optimization.

Potential Use Case: Optimized frontend-to-backend communication for dashboard

The REST API currently provides all necessary functionality for the platform. GraphQL could be added in the future if complex nested queries or optimized data fetching becomes critical for performance.

Protocol Summary

Protocol	Transport	Endpoint	Use Case
REST	HTTPS	`https://api.crowai.dev/api/v1/*`	Traditional integration, CRUD operations, dashboard
MCP	Streamable HTTP (JSON-RPC)	`https://mcp.crowai.dev/mcp`	LLM assistant integration (Claude Desktop, Cursor)
A2A	HTTPS (JSON-RPC)	`https://a2a.crowai.dev/a2a/jsonrpc`	AI agent interoperability
Webhooks	HTTPS	N/A	Event-driven notifications (optional, not implemented)

Authentication

Session-Based Authentication

For dashboard and authenticated user access:

// Session cookie from Better Auth
// Sent automatically with every request via credentials: 'include'
fetch('/api/v1/organizations', {
  credentials: 'include'
});

Better Auth with Drizzle ORM
Session tokens managed automatically
Cookie-based session storage
Session validation at API Gateway

API Key Authentication

For external integrations, MCP, and A2A:

curl -X GET https://api.crowai.dev/api/v1/interactions \
  -H "Authorization: Bearer YOUR_API_KEY"

Key Management:

Generated in dashboard Settings > API Keys (via Better Auth apiKey client)
1-year default expiration
Custom naming for identification
One-time display on creation
Revokable at any time
Key prefix shown for identification after creation

MCP/A2A Key Resolution:

API key is verified against auth service (POST /api/v1/auth/api-key/verify)
Auth service returns user ID or organization ID
If only user ID returned, MCP service resolves organization via user service lookup
Organization ID used to scope all data access

Internal Service Authentication

API Gateway uses X-Internal-Key header for internal service-to-service communication:

Used between API Gateway and microservices (bff-chat-service, bff-qna-service, core services)
Shared secret configured per environment
Contains organization and user context via X-Organization-Id and X-User-Id headers

Rate Limiting

Rate limits are enforced per API key or session:

Tier	Requests/min	Requests/day	Notes
Public	10	100	Unauthenticated requests
Free	60	1,000	Basic tier
Starter	300	50,000	Standard usage
Professional	1,000	500,000	High volume
Enterprise	Custom	Custom	Negotiated limits

Rate Limit Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1640000000

Webhooks (Optional/Future)

Status: Marked as optional. Not part of core architecture.

Rationale: Webhooks add complexity to the platform. Queue-based integrations provide similar functionality with better reliability and control. If webhooks are needed in the future, they can be implemented as an optional add-on.

Alternative: Organizations can use polling or the MCP/A2A protocols for real-time integration needs.

Error Handling

All APIs return consistent error responses:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid date format",
    "details": {
      "field": "date_from",
      "expected": "ISO 8601 format"
    }
  }
}

MCP and A2A return JSON-RPC 2.0 error format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid or unauthorized API key."
  }
}

System Architecture - Overall platform architecture
Services Architecture - Service design
Chat System - AI chat implementation details
Dashboard Features - Dashboard integration cards and setup UI
Website Interaction Tracking - Data ingestion

Overview​

Architecture​

API Types​

1. REST API​

2. MCP Server (Model Context Protocol)​

3. Agent-to-Agent (A2A) Protocol​

4. GraphQL API (Optional/Future)​

Protocol Summary​

Authentication​

Session-Based Authentication​

API Key Authentication​

Internal Service Authentication​

Rate Limiting​

Webhooks (Optional/Future)​

Error Handling​

Related Documentation​