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, GraphQL, Agent2Agent (A2A), and MCP protocols.

Architecture

API Types

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

1. REST API

Audience: External clients, mobile apps, web applications

Features:

• Edge Deployment: Runs on Cloudflare Workers globally
• Authentication: API key and OAuth 2.0
• Rate Limiting: Configurable per-key limits
• Versioning: URL-based versioning (v1, v2)
• Documentation: OpenAPI/Swagger specs

Endpoints:

• /api/v1/organizations - Organization management
• /api/v1/products - Product catalog
• /api/v1/interactions - Interaction data
• /api/v1/insights - Generated insights
• /api/v1/exports - Data export jobs

2. GraphQL API

Audience: Dashboard, complex data queries

Features:

• Flexible Queries: Request only needed fields
• Real-time: Subscriptions via WebSockets
• Introspection: Self-documenting schema
• Batching: Multiple queries per request

Schema Example:

type Query {
  organization(id: ID!): Organization
  interactions(filter: InteractionFilter): [Interaction]
  insights(dateRange: DateRange): InsightsSummary
}

type Mutation {
  createProduct(input: ProductInput!): Product
  triggerExport(config: ExportConfig!): ExportJob
}

3. Agent2Agent (A2A) Protocol

Audience: Enterprise AI systems, agent frameworks

Features:

• Standardized Messaging: JSON-RPC 2.0 based
• Capability Discovery: Dynamic capability negotiation
• Task Delegation: Multi-agent task coordination
• Streaming: Server-sent events for long tasks

4. MCP Server

Audience: LLM applications, Claude, GPT integrations

Features:

• Context Retrieval: Fetch relevant data for LLMs
• Tool Execution: Execute CROW operations
• Resource Access: Access to stored data
• Prompt Templates: Pre-built query templates

Authentication

API Key Authentication

curl -X GET https://api.crow.example.com/v1/interactions \
  -H "Authorization: Bearer YOUR_API_KEY"

OAuth 2.0

For user-context operations, OAuth 2.0 is supported:

1. Authorization Code Flow for web apps
2. Client Credentials Flow for server-to-server
3. PKCE support for mobile/SPA apps

Rate Limiting

Rate limits are enforced per API key:

Tier	Requests/min	Requests/day
Free	60	1,000
Starter	300	50,000
Professional	1,000	500,000
Enterprise	Custom	Custom

Error Handling

All APIs return consistent error responses:

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

Related Documentation

• System Architecture - Overall platform architecture
• Services Architecture - Service design
• Website Interaction Tracking - Data ingestion