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, dashboard

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, v2)
• Documentation: OpenAPI/Swagger specs

Endpoints:

• /api/v1/organizations - Organization management
• /api/v1/users - User management
• /api/v1/products - Product catalog
• /api/v1/interactions - Interaction data
• /api/v1/patterns - Pattern data
• /api/v1/analytics - Analytics and billing
• /api/v1/notifications - User notifications

2. 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.

3. Agent2Agent (A2A) Protocol

Audience: Enterprise AI systems, agent frameworks

Features:

• Standardized Messaging: Agent-to-agent communication protocol
• Capability Discovery: Dynamic capability negotiation
• Task Delegation: Multi-agent task coordination
• Authentication Required: API key or system-level auth
• Calls MCP Server: Proxies requests to MCP for data access

Integration: External agents can call CROW's A2A service to interact with interaction and pattern data.

4. MCP Server

Audience: LLM applications, Claude, ChatGPT, other AI tools

Features:

• Context Retrieval: Fetch relevant data for LLM context
• Tool Execution: Execute CROW operations via Interaction and Pattern services
• Resource Access: Access stored interactions and patterns
• API Key Required: Authentication via API key
• Routes Through Gateway: Acts as external party for security

Implementation: Built on Cloudflare MCP Workers

Standard Compliance: Follows Model Context Protocol specification

Exposed Services:

• Interaction Service (read access)
• Pattern Service (read access)
• Query capabilities for LLM context enrichment

Protocol Summary

Protocol	Transport	Use Case
REST	HTTPS	Traditional integration, CRUD operations
Agent2Agent	JSON-RPC/WSS	AI agent interoperability
MCP	Streamable HTTP	LLM assistant integration
Webhooks	HTTPS	Event-driven notifications (optional)
GraphQL	HTTPS/WSS	Flexible queries, real-time subscriptions (optional)

Authentication

Session-Based Authentication

For dashboard and authenticated user access:

// Session token from Better Auth
// Stored in frontend, sent with every request
fetch('/api/v1/organizations', {
  headers: {
    'Cookie': 'session=...'
  }
});

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

API Key Authentication

For external integrations and SDK usage:

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

Key Management:

• Generated in dashboard Settings > API Keys
• Configurable expiration
• Permission-based access (interactions, patterns)
• Revokable at any time
• Encrypted at rest

JWT Tokens (Internal)

API Gateway converts sessions/API keys to JWTs for internal service communication:

• Used between microservices
• No TTL (optimized for performance)
• Contains user/org context and permissions
• Cached mapping (1-5 min) to reduce database calls

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"
    }
  }
}

Related Documentation

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