API Documentation

Everything you need to build with Ricochet. Production-ready APIs, typed SDKs, and real-world examples.

v1.2.0 · Stablehttps://api.ricochet.group/v1Get API Key →

Authentication

All API requests must include your API key in the Authorization header using Bearer token format. You can generate and manage API keys from your dashboard.

Authorization: Bearer YOUR_API_KEY

Never expose your API key in client-side code. Use environment variables and server-side requests only.

Quick Start

Install the official SDK, initialize the client with your API key, and make your first call in under two minutes.

1. Install the SDK

npm install @ricochet/sdk

2. Initialize and call

import { Ricochet } from "@ricochet/sdk";

// Initialize the client
const client = new Ricochet({
  apiKey: process.env.RICOCHET_API_KEY,
});

// Analyze communication patterns
const result = await client.signal.analyze({
  workspace_id: "ws_abc123",
  channels: ["general", "engineering"],
  date_range: { from: "2026-04-01", to: "2026-04-30" },
});

console.log(result.insights.response_rate); // 0.87

Core Endpoints

The five primary endpoints cover everything from communication analytics to support automation.

POST/signal/analyze

Analyze communication patterns across a workspace or channel.

Request

{
  "workspace_id": "ws_abc123",
  "channels": ["general", "engineering"],
  "date_range": {
    "from": "2026-04-01",
    "to": "2026-04-30"
  }
}

Response

{
  "id": "sig_xk92ms",
  "status": "complete",
  "insights": {
    "response_rate": 0.87,
    "avg_response_time_min": 12,
    "top_collaborators": ["alice", "bob"]
  }
}

GET/nexus/tasks

List all tasks for a given workspace, with optional filters.

Request

GET /nexus/tasks?workspace_id=ws_abc123&status=open&limit=20

Response

{
  "tasks": [
    {
      "id": "task_001",
      "title": "Finalize Q3 OKRs",
      "status": "open",
      "assignee": "alice@acme.com",
      "due": "2026-05-20"
    }
  ],
  "total": 47,
  "page": 1
}

POST/compose/generate

Generate structured AI content — emails, summaries, docs.

Request

{
  "prompt": "Write a follow-up email for a sales demo that went well",
  "tone": "professional",
  "max_length": 200
}

Response

{
  "id": "comp_9s2lk",
  "content": "Hi [Name], Thank you for joining us today...",
  "tokens_used": 148,
  "model": "ricochet-compose-v2"
}

GET/blueprint/plans

List strategic plans and OKR sets for your organization.

Request

GET /blueprint/plans?org_id=org_xyz&quarter=Q2-2026

Response

{
  "plans": [
    {
      "id": "plan_88f2",
      "title": "Growth — Q2 2026",
      "objectives": 3,
      "key_results": 12,
      "progress": 0.61
    }
  ]
}

POST/relay/tickets

Create a new customer support ticket routed via Relay AI.

Request

{
  "subject": "Cannot export CSV report",
  "body": "When I click Export, nothing happens in Chrome.",
  "priority": "high",
  "customer_email": "user@example.com"
}

Response

{
  "ticket_id": "rlx_5512",
  "status": "open",
  "assigned_to": "relay-ai",
  "eta_min": 5
}

Rate Limits

Rate limits are enforced per API key per minute. When exceeded, the API returns 429 Too Many Requests. Response headers include X-RateLimit-Remaining and X-RateLimit-Reset.

Plan	Limit	Notes
Starter	100 req/min	Burst up to 150 for 10 s
Pro	1,000 req/min	Burst up to 1,500 for 10 s
Developer	5,000 req/min	Burst up to 7,500 for 10 s
Business	Unlimited	Fair use policy applies

SDKs

Official, fully typed SDKs for all major languages. All SDKs are open-source and MIT licensed.

JavaScript / TypeScript

Install

npm install @ricochet/sdk

Example

import { Ricochet } from "@ricochet/sdk";

const client = new Ricochet({
  apiKey: process.env.RICOCHET_API_KEY,
});

const result = await client.signal.analyze({
  workspace_id: "ws_abc123",
});

Python

Install

pip install ricochet-sdk

Example

from ricochet import Ricochet

client = Ricochet(api_key=os.environ["RICOCHET_API_KEY"])

result = client.signal.analyze(
    workspace_id="ws_abc123"
)

Install

go get github.com/ricochet-group/sdk-go

Example

client := ricochet.NewClient(os.Getenv("RICOCHET_API_KEY"))

result, err := client.Signal.Analyze(ctx,
  &ricochet.AnalyzeRequest{
    WorkspaceID: "ws_abc123",
  })

Changelog

Recent API updates. We maintain backwards compatibility across minor versions.

v1.2.0May 8, 2026

Added /blueprint/plans endpoint with OKR filtering
Compose API now supports tone parameter
Improved rate limit headers (X-RateLimit-*)

v1.1.0April 2, 2026

Webhook marketplace launched — 40+ pre-built integrations
Signal API response time down 40%
Python SDK reaches stable v1.0

v1.0.0March 1, 2026

Developer API v1.0 general availability
Signal, Nexus, Compose, Relay APIs stable
JavaScript SDK released

View full changelog →