CACP Documentation · Phoenix Framework

Application Overview

CACP is a multi-tenant transport and orchestration layer for AI agents. It exposes a REST API for registration, messaging, tasks, groups, billing, and audit operations, and a Phoenix Channel transport for low-latency real-time exchange.

REST Base URL: /v1

WebSocket URL: ws://localhost:4001/ws/v1

Topic Convention: agent:<agent_id>

Getting Started

1) Start dependencies and run `mix ecto.migrate`.
2) Start server with `mix phx.server` (dev URL: http://localhost:4001).
3) Create an org user via /signup or seed data.
4) Create JWT with `agent_id` + `organization_id` claims.
5) Register first agent over `POST /v1/agents`.
6) Send first message via `POST /v1/messages`.
7) Connect socket at `ws://localhost:4001/ws/v1` and join topic `agent:<agent_id>`.

Core Concepts

Organization: tenant scope for security, usage, and billing.
Agent: addressable runtime participant.
Capability: discoverable skill tag used by routing/discovery.
Message: primary protocol envelope.
Task: persistent async work item.
Group: set of agents for coordinated broadcast.
RPC: request/reply flow over protocol transport.
Offline queue: guaranteed eventual delivery when recipients reconnect.
Audit log: immutable activity record for compliance and debugging.

Authentication And Tenant Context

Use either Authorization: Bearer <jwt> or X-API-Key.
Tenant context is derived from JWT organization_id and/or X-Organization-Id.
If token org and header org mismatch, server keeps token org and marks mismatch state.
Rate limit headers: x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset.
Common auth failures include invalid token, missing org context, and quota/rate limit exhaustion.

HTTP API Reference

Agents

GET /v1/agents List Agents

List all known agents for the active organization.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns matching agents.

Headers

Authorization or X-API-Key
X-Organization-Id

Query Params

status (string) - optional - Filter by online/offline.
capability (string) - optional - Filter by capability.

Common Errors

5003 - Organization context required

Example Request

{}

Example Response

{
  "agents": [
    {
      "agent_id": "writer-agent-1",
      "availability": "online"
    }
  ]
}

POST /v1/agents Register Agent

Auth

Bearer token or API key; tenant context required.

Success

201 - Agent registered and immediately queryable.

Headers

Authorization: Bearer <jwt> OR X-API-Key: cacp_<key>
X-Organization-Id: <org_id> (required when org claim is absent)

Body / Path Fields

agent_id (string) - required - Unique agent identifier.
agent_type (string) - optional - Logical type label.
framework (string) - optional - Runtime framework name.
capabilities (array<string>) - optional - Supported skills.
version (string) - optional - Agent software version.
metadata (object) - optional - Arbitrary context.

Common Errors

3001 - Invalid registration payload
5003 - Organization context required

Example Request

{
  "agent_id": "writer-agent-1",
  "agent_type": "service",
  "capabilities": [
    "summarization",
    "drafting"
  ],
  "framework": "langchain",
  "version": "1.3.2"
}

Example Response

{
  "agent_id": "writer-agent-1",
  "status": "registered"
}

DELETE /v1/agents/:id Delete Agent

Remove an agent registration.

Auth

Bearer token or API key; tenant context required.

Success

200 - Agent removed.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Agent ID in URL path.

Common Errors

2001 - Agent not found

Example Request

{}

Example Response

{
  "status": "deleted"
}

GET /v1/agents/:id Get Agent

Fetch details for one agent.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns agent details.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Agent ID in URL path.

Common Errors

2001 - Agent not found

Example Request

{}

Example Response

{
  "agent": {
    "agent_id": "writer-agent-1"
  }
}

POST /v1/agents/discover Discover Agents

Semantic or criteria-based discovery for candidate agents.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns discovery candidates and scores.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

query (string) - required - Discovery intent in natural language.
availability (string) - optional - Optional availability filter.
limit (integer) - optional - Maximum matches.

Common Errors

3001 - Missing discovery query

Example Request

{
  "limit": 3,
  "query": "agent that can write release notes"
}

Example Response

{
  "agents": [
    {
      "agent_id": "writer-agent-1",
      "score": 0.98
    }
  ]
}

GET /v1/agents/query Query Agents

Find agents by capability and optional availability filters.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns agents satisfying query.

Headers

Authorization or X-API-Key
X-Organization-Id

Query Params

capability (string) - required - Capability to match.
availability (string) - optional - online or offline.

Common Errors

3001 - Missing capability

Example Request

{}

Example Response

{
  "agents": [
    {
      "agent_id": "planner-agent-1"
    }
  ]
}

Audit Logs

GET /v1/audit-logs List Audit Logs

Query security and activity events.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns audit events.

Headers

Authorization or X-API-Key
X-Organization-Id

Query Params

page (integer) - optional - Page number.
per_page (integer) - optional - Page size.
actor_type (string) - optional - Filter actor type.
action (string) - optional - Filter action.
resource_type (string) - optional - Filter resource type.
from (string) - optional - ISO8601 start timestamp.
to (string) - optional - ISO8601 end timestamp.

Example Request

{}

Example Response

{
  "logs": [
    {
      "action": "message.sent",
      "id": "log_1"
    }
  ]
}

GET /v1/audit-logs/:id Get Audit Log

Fetch one audit event record.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns audit log entry.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Audit log ID in URL path.

Common Errors

3001 - Audit log not found

Example Request

{}

Example Response

{
  "log": {
    "action": "agent.registered",
    "id": "log_1"
  }
}

GET /v1/audit-logs/export Export Audit Logs

Export audit logs in CSV format for compliance and reporting.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns CSV attachment.

Headers

Authorization or X-API-Key
X-Organization-Id

Query Params

actor_type (string) - optional - Filter actor type.
action (string) - optional - Filter action.
resource_type (string) - optional - Filter resource type.
from (string) - optional - ISO8601 start timestamp.
to (string) - optional - ISO8601 end timestamp.

Example Request

{}

Example Response

{
  "file": "audit_logs.csv"
}

Billing

DELETE /v1/billing/credits/auto-top-up Disable Auto Top-Up

Disable automatic credit replenishment.

Auth

Bearer token or API key; tenant context required.

Success

200 - Auto top-up disabled.

Headers

Authorization or X-API-Key
X-Organization-Id

Example Request

{}

Example Response

{
  "status": "disabled"
}

POST /v1/billing/credits/auto-top-up Set Auto Top-Up

Enable or update automatic credit top-up policy.

Auth

Bearer token or API key; tenant context required.

Success

200 - Auto top-up saved.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

threshold_cents (integer) - required - Trigger threshold.
top_up_amount_cents (integer) - required - Recharge amount.
payment_method_id (string) - required - Funding source.

Common Errors

3001 - Invalid auto top-up configuration

Example Request

{
  "payment_method_id": "pm_1",
  "threshold_cents": 500,
  "top_up_amount_cents": 5000
}

Example Response

{
  "status": "enabled"
}

GET /v1/billing/credits/balance Get Credit Balance

Return current balance and thresholds.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns available balance.

Headers

Authorization or X-API-Key
X-Organization-Id

Example Request

{}

Example Response

{
  "auto_top_up": true,
  "balance_cents": 12340
}

POST /v1/billing/credits/purchase Purchase Credits

Buy prepaid credits for message and RPC usage.

Auth

Bearer token or API key; tenant context required.

Success

200 - Purchase initiated.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

amount_cents (integer) - required - Credit purchase amount in cents.
currency (string) - optional - Defaults to usd.
provider (string) - optional - stripe or nowpayments.

Common Errors

3001 - Invalid credit purchase payload

Example Request

{
  "amount_cents": 2000,
  "currency": "usd",
  "provider": "stripe"
}

Example Response

{
  "payment_id": "pay_1",
  "status": "pending"
}

GET /v1/billing/credits/transactions List Credit Transactions

List debits and credits with pagination.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns transaction ledger.

Headers

Authorization or X-API-Key
X-Organization-Id

Query Params

page (integer) - optional - Page number.
per_page (integer) - optional - Page size.

Example Request

{}

Example Response

{
  "transactions": [
    {
      "amount_cents": 3,
      "type": "debit"
    }
  ]
}

GET /v1/billing/invoices List Invoices

List invoices for the organization.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns invoices.

Headers

Authorization or X-API-Key
X-Organization-Id

Query Params

page (integer) - optional - Page number.
per_page (integer) - optional - Page size.

Example Request

{}

Example Response

{
  "invoices": [
    {
      "id": "inv_1",
      "status": "paid"
    }
  ]
}

GET /v1/billing/invoices/:id Get Invoice

Fetch invoice detail record.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns invoice details.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Invoice ID.

Common Errors

3001 - Invoice not found

Example Request

{}

Example Response

{
  "invoice": {
    "id": "inv_1",
    "total_cents": 2300
  }
}

GET /v1/billing/invoices/:id/pdf Get Invoice PDF

Download invoice PDF document.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns PDF binary stream.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Invoice ID.

Common Errors

3001 - Invoice PDF not found

Example Request

{}

Example Response

{
  "content_type": "application/pdf"
}

GET /v1/billing/payment-methods List Payment Methods

List saved payment methods.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns methods.

Headers

Authorization or X-API-Key
X-Organization-Id

Example Request

{}

Example Response

{
  "payment_methods": [
    {
      "brand": "visa",
      "id": "pm_1"
    }
  ]
}

POST /v1/billing/payment-methods Create Payment Method Setup

Create setup intent / attach payment method.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns setup secret and workflow details.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

provider (string) - optional - Defaults to stripe.
payment_method_type (string) - optional - card etc.

Common Errors

3001 - Invalid payment method request

Example Request

{
  "payment_method_type": "card",
  "provider": "stripe"
}

Example Response

{
  "client_secret": "seti_..._secret_..."
}

DELETE /v1/billing/payment-methods/:id Delete Payment Method

Remove one payment method.

Auth

Bearer token or API key; tenant context required.

Success

200 - Payment method removed.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Payment method ID.

Common Errors

3001 - Payment method not found

Example Request

{}

Example Response

{
  "status": "deleted"
}

PATCH /v1/billing/payment-methods/:id/set-default Set Default Payment Method

Mark a payment method as default.

Auth

Bearer token or API key; tenant context required.

Success

200 - Default payment method updated.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Payment method ID.

Common Errors

3001 - Payment method not found

Example Request

{}

Example Response

{
  "status": "updated"
}

GET /v1/billing/payments/:payment_id/status Get Payment Status

Poll payment session status by payment id.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns payment lifecycle state.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

payment_id (path) - required - Provider payment/session ID.

Common Errors

3001 - Payment not found

Example Request

{}

Example Response

{
  "payment_id": "pay_1",
  "status": "confirmed"
}

GET /v1/billing/payments/currencies List Supported Currencies

List currencies accepted by payment providers.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns supported currencies.

Headers

Authorization or X-API-Key
X-Organization-Id

Example Request

{}

Example Response

{
  "currencies": [
    "usd",
    "eur",
    "usdt"
  ]
}

GET /v1/billing/payments/estimate Estimate Payment

Estimate provider totals and fees for a requested amount.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns estimated totals and fees.

Headers

Authorization or X-API-Key
X-Organization-Id

Query Params

provider (string) - required - stripe or nowpayments.
amount_cents (integer) - required - Requested amount.
currency (string) - optional - Currency code.

Common Errors

3001 - Invalid estimate query

Example Request

{}

Example Response

{
  "fee_cents": 90,
  "subtotal_cents": 2000,
  "total_cents": 2090
}

GET /v1/billing/payments/minimum Get Minimum Payment

Return minimum purchase amounts per provider/currency.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns minimum thresholds.

Headers

Authorization or X-API-Key
X-Organization-Id

Query Params

provider (string) - optional - Optional provider filter.
currency (string) - optional - Optional currency filter.

Example Request

{}

Example Response

{
  "currency": "usd",
  "minimum_cents": 500
}

GET /v1/billing/subscriptions List Subscriptions

List subscriptions for the organization.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns subscriptions.

Headers

Authorization or X-API-Key
X-Organization-Id

Example Request

{}

Example Response

{
  "subscriptions": [
    {
      "id": "sub_1",
      "status": "active"
    }
  ]
}

DELETE /v1/billing/subscriptions/:id Cancel Subscription

Cancel an active subscription.

Auth

Bearer token or API key; tenant context required.

Success

200 - Cancellation accepted.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Subscription ID.

Common Errors

3001 - Subscription not found

Example Request

{}

Example Response

{
  "status": "cancelled"
}

GET /v1/billing/subscriptions/:id Get Subscription

Fetch one subscription by id.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns subscription details.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Subscription ID.

Common Errors

3001 - Subscription not found

Example Request

{}

Example Response

{
  "subscription": {
    "id": "sub_1",
    "status": "active"
  }
}

POST /v1/billing/subscriptions/create Create Subscription Checkout

Start checkout flow for recurring subscription.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns checkout URL or payment metadata.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

provider (string) - required - stripe or nowpayments.
plan_type (string) - required - starter|pro|enterprise.
payment_flow (string) - optional - direct or hosted (nowpayments).

Common Errors

3001 - Invalid provider or plan

Example Request

{
  "plan_type": "pro",
  "provider": "stripe"
}

Example Response

{
  "checkout_url": "https://checkout.stripe.com/..."
}

Groups

GET /v1/groups List Groups

List all groups in the organization.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns groups.

Headers

Authorization or X-API-Key
X-Organization-Id

Example Request

{}

Example Response

{
  "groups": [
    {
      "id": "grp_123",
      "name": "Document Team"
    }
  ]
}

POST /v1/groups Create Group

Create a named agent group for team broadcasts.

Auth

Bearer token or API key; tenant context required.

Success

201 - Group created.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

name (string) - required - Group name.
description (string) - optional - Optional description.
metadata (object) - optional - Custom fields.

Common Errors

3001 - Invalid group payload

Example Request

{
  "description": "Writers and reviewers",
  "name": "Document Team"
}

Example Response

{
  "group": {
    "id": "grp_123",
    "name": "Document Team"
  }
}

DELETE /v1/groups/:id Delete Group

Delete a group and membership associations.

Auth

Bearer token or API key; tenant context required.

Success

200 - Group deleted.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Group ID in URL path.

Common Errors

3001 - Group not found

Example Request

{}

Example Response

{
  "status": "deleted"
}

GET /v1/groups/:id Get Group

Retrieve group details and members.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns group details.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Group ID in URL path.

Common Errors

3001 - Group not found

Example Request

{}

Example Response

{
  "group": {
    "id": "grp_123",
    "members": [
      "writer-agent-1"
    ]
  }
}

PUT /v1/groups/:id Update Group

Update group name, description, and metadata.

Auth

Bearer token or API key; tenant context required.

Success

200 - Group updated.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Group ID in URL path.
name (string) - optional - New name.
description (string) - optional - New description.
metadata (object) - optional - Updated metadata.

Common Errors

3001 - Invalid update payload

Example Request

{
  "name": "Document Team v2"
}

Example Response

{
  "group": {
    "id": "grp_123",
    "name": "Document Team v2"
  }
}

POST /v1/groups/:id/members Add Group Member

Attach an agent to a group.

Auth

Bearer token or API key; tenant context required.

Success

200 - Member added.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Group ID in URL path.
agent_id (string) - required - Agent ID to add.
role (string) - optional - Group role label.

Common Errors

2001 - Agent not found

Example Request

{
  "agent_id": "reviewer-agent-1",
  "role": "reviewer"
}

Example Response

{
  "group_id": "grp_123",
  "status": "member_added"
}

DELETE /v1/groups/:id/members/:agent_id Remove Group Member

Detach an agent from a group.

Auth

Bearer token or API key; tenant context required.

Success

200 - Member removed.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Group ID in URL path.
agent_id (path) - required - Agent ID in URL path.

Common Errors

3001 - Member not found

Example Request

{}

Example Response

{
  "status": "member_removed"
}

POST /v1/groups/:id/message Broadcast To Group

Send one message to all online/offline group members.

Auth

Bearer token or API key; tenant context required.

Success

202 - Broadcast accepted.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Group ID in URL path.
message (object) - required - CACP message payload.

Common Errors

3001 - Invalid message payload

Example Request

{
  "message": {
    "message_id": "msg-2001",
    "message_type": "notification",
    "payload": {
      "content": "Deploy in 15 minutes"
    }
  }
}

Example Response

{
  "group_id": "grp_123",
  "status": "queued"
}

Messages

POST /v1/messages Send Message

Dispatch a protocol message for direct, broadcast, group, or capability routing.

Auth

Bearer token or API key; tenant context required.

Success

202 - Accepted and routed/queued.

Headers

Authorization: Bearer <jwt> OR X-API-Key: cacp_<key>
X-Organization-Id: <org_id>
Idempotency-Key: <optional key>

Body / Path Fields

message_id (string) - required - Client-generated unique id.
sender (object) - required - Sender identity.
recipient (object) - required - Routing target.
message_type (string) - required - Protocol message type.
payload (object) - required - Application payload.
metadata (object) - optional - Trace and custom metadata.

Common Errors

2001 - Agent not found
2008 - No matching agents
6001 - Rate limit exceeded
7001 - Insufficient funds

Example Request

{
  "message_id": "msg-1001",
  "message_type": "task",
  "payload": {
    "instruction": "review this draft"
  },
  "recipient": {
    "agent_id": "reviewer-agent-1",
    "discovery": "direct"
  },
  "sender": {
    "agent_id": "writer-agent-1"
  }
}

Example Response

{
  "cost_cents": 2,
  "message_id": "msg-1001",
  "recipients": [
    "reviewer-agent-1"
  ],
  "status": "delivered"
}

GET /v1/messages/:id Get Message

Retrieve message delivery status and metadata.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns message record.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Message ID in URL path.

Common Errors

3001 - Invalid or unknown message id

Example Request

{}

Example Response

{
  "message": {
    "message_id": "msg-1001",
    "status": "delivered"
  }
}

Tasks

GET /v1/tasks List Tasks

List tasks with filter and pagination controls.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns task list.

Headers

Authorization or X-API-Key
X-Organization-Id

Query Params

status (string) - optional - Filter status.
agent_id (string) - optional - Filter by recipient.
page (integer) - optional - Page number.
per_page (integer) - optional - Page size.

Example Request

{}

Example Response

{
  "tasks": [
    {
      "id": "task_123",
      "status": "queued"
    }
  ]
}

POST /v1/tasks Create Task

Create asynchronous work for one target agent.

Auth

Bearer token or API key; tenant context required.

Success

201 - Task queued.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

task_id (string) - optional - Optional custom task id.
task_type (string) - required - Task category.
recipient_agent_id (string) - required - Target agent.
payload (object) - required - Task payload.
priority (string) - optional - low|normal|high|critical.
scheduled_at (string) - optional - ISO8601 future execution.
max_retries (integer) - optional - Retry budget.
timeout_seconds (integer) - optional - Execution timeout.

Common Errors

3001 - Invalid task payload

Example Request

{
  "payload": {
    "source": "s3://docs/input.md"
  },
  "priority": "high",
  "recipient_agent_id": "writer-agent-1",
  "task_type": "document.transform"
}

Example Response

{
  "status": "queued",
  "task_id": "task_123"
}

GET /v1/tasks/:id Get Task

Fetch one task by id.

Auth

Bearer token or API key; tenant context required.

Success

200 - Returns task details.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Task ID in URL path.

Common Errors

3001 - Task not found

Example Request

{}

Example Response

{
  "task": {
    "id": "task_123",
    "status": "running"
  }
}

POST /v1/tasks/:id/cancel Cancel Task

Cancel a queued or running task.

Auth

Bearer token or API key; tenant context required.

Success

200 - Cancellation accepted.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Task ID in URL path.

Common Errors

3001 - Task cannot be cancelled

Example Request

{}

Example Response

{
  "status": "cancelled",
  "task_id": "task_123"
}

POST /v1/tasks/:id/retry Retry Task

Requeue a failed task with existing payload.

Auth

Bearer token or API key; tenant context required.

Success

200 - Retry accepted.

Headers

Authorization or X-API-Key
X-Organization-Id

Body / Path Fields

id (path) - required - Task ID in URL path.

Common Errors

3001 - Task cannot be retried

Example Request

{}

Example Response

{
  "status": "queued",
  "task_id": "task_123"
}

Webhooks

POST /webhooks/nowpayments NOWPayments Webhook

Receive NOWPayments payment status callbacks.

Auth

No JWT/API key. Signature hash validation required.

Success

200 - Returns processed or already_processed.

Headers

X-Nowpayments-Sig: <signed header>

Body / Path Fields

event (object) - required - NOWPayments payload.

Common Errors

3001 - Invalid signature or payload

Example Request

{
  "payment_id": "np_1",
  "payment_status": "finished"
}

Example Response

{
  "status": "processed"
}

POST /webhooks/stripe Stripe Webhook

Receive Stripe events to update subscriptions, invoices, and payments.

Auth

No JWT/API key. Request authenticity validated by Stripe signature.

Success

200 - Returns processed or already_processed.

Headers

Stripe-Signature: <signed header>

Body / Path Fields

event (object) - required - Stripe event payload.

Common Errors

3001 - Invalid signature or payload

Example Request

{
  "id": "evt_1",
  "type": "invoice.payment_succeeded"
}

Example Response

{
  "status": "processed"
}

WebSocket And Channels

Connect to ws://localhost:4001/ws/v1, pass a JWT with agent_id and organization_id, then join topic agent:<agent_id>.

Inbound Events

send

{"message": <CACP message object>}.

Dispatches a protocol message over broker routing with rate/quota checks.
rpc_request

{"message": <RPC request envelope>}.

Initiates RPC processing; can return immediate response or async stream.
heartbeat

{"timestamp": "ISO8601"} (payload optional).

Refreshes connection liveness and returns heartbeat ack.
health_report

{"metrics": {...}}.

Submits agent health metrics captured by the health collector.
disconnect

{"reason": "<text>"}.

Graceful disconnect and agent unregister.

Outbound Events

ack

Message acceptance and delivery metadata.
message

Broker-delivered inbound protocol message.
error

Protocol or validation failure details with numeric code.
rpc_response

Immediate RPC result.
rpc_error

RPC failure details.
rpc_chunk

Streaming chunk for long-running RPC.
rpc_cancelled

RPC cancellation notification.
heartbeat

Liveness confirmation.
health_check_request

Server-initiated health probe.
health_report_ack

Health report persistence acknowledgement.

Dashboard Guide

Path	Page	Purpose
`/dashboard`	Overview	Global health and usage summary.
`/dashboard/agents`	Agents	Registry, status, and capabilities.
`/dashboard/messages`	Messages	Recent message traffic and status.
`/dashboard/api-playground`	API Playground	Interactive HTTP API testing.
`/dashboard/websocket-playground`	WS Playground	Interactive channel testing.
`/dashboard/health`	Health	Agent and system health metrics.
`/dashboard/analytics`	Analytics	Usage, trends, and KPIs.
`/dashboard/alerts`	Alerts	Threshold and anomaly alerting.
`/dashboard/team`	Team	Users, membership, and roles.
`/dashboard/settings`	Settings	Organization and key configuration.
`/dashboard/billing`	Billing	Credits, subscriptions, invoices.

Architecture

ConnectionManager: tracks connected sockets and heartbeats.
AgentRegistry: ETS-backed capability and availability registry.
MessageRouter + Dispatcher: resolves routing and persistence.
RPC: request/response orchestration including streaming.
RateLimiter: request and message throughput controls.
TaskQueue + OfflineQueue: DB-backed asynchronous delivery.
Usage.Meter + Billing modules: metering, credits, and subscriptions.
HealthCollector + HealthMetrics + Alerting.Engine: health telemetry and alarms.
Analytics.Aggregator: usage and operational analytics.

Data Model

organizations: tenant boundary and plan settings.
users and api_keys: dashboard auth and key-based integration auth.
agents: registered agent identity + capabilities.
messages and offline_messages: protocol message persistence.
tasks: queued async jobs and state transitions.
agent_groups and group memberships: team routing.
usage_events: billing/metering ledger.
subscriptions, payment_methods, invoices, credits: billing entities.
audit_logs: compliance trail.
agent_health_metrics and alerts: reliability monitoring.

AI Agent Guide

Use deterministic message_id and optional idempotency key for retries.
Always include trace metadata (correlation_id, workflow id, retry count).
Treat 6001, 6002, and 7001 as backoff or funding signals.
For long operations, prefer task endpoints or streaming RPC chunks.
Use groups/capabilities for adaptive routing instead of hardcoding recipient ids.

Integrations

LangChain

Map tools/chains to CACP messages and use capability tags for specialized agents.

AutoGen

Use one channel topic per AutoGen agent; map conversation turns to `message_type` values.

CrewAI

Represent crew roles as CACP groups and route team tasks through group broadcasts.

Errors And Troubleshooting

Code	Reason	Surface
`2001`	Agent not found	HTTP + WS
`2008`	No matching agents	HTTP + WS
`3001`	Invalid request payload	HTTP + WS
`5003`	Missing organization context	HTTP + WS
`6001`	Rate limit exceeded	HTTP + WS
`6002`	Quota exceeded	WS
`7001`	Insufficient funds	HTTP + WS

401/403-like failures: verify JWT validity, claims, and org context.
429/6001: back off and honor reset headers; smooth burst traffic.
No recipients: validate direct IDs, capability names, and group membership.
Webhook failures: confirm provider signature secret and raw body handling.