HomeAPI Reference

API Reference

Complete reference for the Ricord API. Store knowledge, search memories, manage integrations, and control your account programmatically.

Base URL: https://api.ricord.ai

Quick Start

Get started in under a minute. Create an account, grab your API key from the dashboard, and make your first request.

1. Store a knowledge article

bash
curl -X POST https://api.ricord.ai/v1/wiki \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q2 Product Roadmap",
    "content": "Ship v2 search by April. Mobile beta in May.",
    "type": "fact",
    "tags": ["product", "roadmap"]
  }'

2. Search your knowledge base

bash
curl -X POST https://api.ricord.ai/v1/wiki/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "What is the mobile plan?" }'

3. Check your credit balance

bash
curl https://api.ricord.ai/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

API Playground

Test the API directly from your browser. Paste your API key and try a search query.

Authentication

All API requests require authentication via the Authorization header. Ricord supports two authentication methods:

API Key

Best for server-side and agent integrations. Create keys in the dashboard or via the API.

http
Authorization: Bearer hx_live_abc123...

Firebase ID Token

Best for client-side apps. Obtain via Firebase Auth SDK. Required for API key management endpoints.

http
Authorization: Bearer eyJhbGciOiJS...
Rate limits: Vary by tier. Free: 20 req/min. Pro: 60 req/min. Team: 120 req/min. Rate limit headers are included in every response:X-RateLimit-Remaining, X-RateLimit-Reset.

Knowledge Wiki

Structured, versioned knowledge articles with semantic search. Articles support types (fact, procedure, decision, reference, playbook, anti-pattern, episode), maturity levels, conflict detection, and automatic deprecation.

Episodic Memory

Store and search agent memories — situations, outcomes, and reflections. Memories are private per user, expire after 90 days by default, and support similarity search with tag and temporal filtering.

Embeddings

OpenAI-compatible embeddings endpoint. Supports OpenAI and Google embedding models with automatic provider routing. Returns embeddings in the standard OpenAI format.

Integrations

Execute actions across 200+ connected services (Gmail, GitHub, Slack, Twitter, Notion, and more) via Composio. Connect accounts through OAuth, then execute tools programmatically.

Assets

Upload and manage files with permanent and staging lifecycle zones. Staging files auto-expire; permanent files persist indefinitely. Supports base64 content or URL-based ingestion.

Account & Usage

Monitor your credit balance, usage patterns, and rate limits. All usage endpoints are free.

API Keys

Create and manage API keys programmatically. These endpoints require Firebase ID token authentication (not API key auth). Max 25 keys per account.

Health

Service health and status endpoints. No authentication required.

Error Handling

The API returns consistent error objects across all endpoints. Errors include a machine-readable type and a human-readable message.

Code
Type
Description
400
invalid_request_error
Missing or invalid parameters
401
authentication_error
Missing or invalid API key / token
402
insufficient_credits_error
Credit balance too low for this operation
403
permission_error
API key lacks required permission
429
rate_limit_error
Rate limit exceeded (check Retry-After header)
500
internal_error
Server error — retry with exponential backoff
502
provider_error
Upstream provider failure (OpenAI, Google, etc.)
503
service_unavailable
Service temporarily unavailable

Error Response Format

json
{
  "error": {
    "type": "insufficient_credits_error",
    "message": "Insufficient credits. Balance: 2, required: 10",
    "param": null,
    "code": "insufficient_credits"
  }
}

Credit Costs Summary

1 credit = $0.01 USD. All paid endpoints show the charge in the X-Credits-Charged response header and a credits_charged field in the response body.

Endpoint
Credits
POST /v1/wiki (article)
3
POST /v1/wiki (episode)
1
POST /v1/wiki/search
1
POST /v1/search (hybrid)
1
PUT /v1/wiki/:id (content changed)
3
POST /v1/memory
1
POST /v1/memory/search
1
POST /v1/embeddings
1-13/1M tokens
POST /v1/composio/execute
20
POST /v1/assets
2
All GET endpoints
Free
DELETE endpoints
Free
Feedback endpoints
Free

Ready to get started?

Create a free account and get 100 credits to start building.

Get API KeyBack to home