API Guide

The Recurse API gives you complete programmatic control over your knowledge base. Use it when you need custom integrations, batch processing, or fine-grained control over how content is processed and retrieved.

Overview

The API follows RESTful conventions and returns JSON responses. All endpoints require authentication via API key or JWT token.

# Example: Search your knowledge base
curl -X GET "https://api.recurse.dev/search/?query=machine+learning" \
  -H "Authorization: Bearer YOUR_API_KEY"

Key Capabilities

Content Management

• Save content - Ingest documents, URLs, and raw text
• Track processing - Monitor document analysis status
• Manage documents - List, retrieve, and delete content

Search & Retrieval

• Semantic search - Find content by meaning, not just keywords
• Type filtering - Search specific frame types (claims, definitions, etc.)
• Field selection - Control response detail with field sets

Graph Navigation

• Tree traversal - Navigate parent/child relationships
• Neighbor discovery - Find related content
• Relationship exploration - Understand how content connects

Response Field Sets

Control response verbosity with the field_set parameter:

See Scoping and Filtering for detailed field set documentation.

Response Structure

Search results are grouped by document:

{
  "nodes": [
    {
      "document": {
        "id": "doc123",
        "title": "Guide to ML",
        "type": "article"
      },
      "citations": [
        {
          "id": "frame456",
          "title": "Training Models",
          "relevance_score": 0.85,
          "citation_index": 1
        }
      ]
    }
  ],
  "total_found": 10,
  "search_time_ms": 150
}

Getting Started

Authentication

Include your API key in the Authorization header:

curl -H "Authorization: Bearer rg_YOUR_API_KEY" \
  "https://api.recurse.dev/search/?query=..."

Or use the X-API-Key header:

curl -H "X-API-Key: rg_YOUR_API_KEY" \
  "https://api.recurse.dev/search/?query=..."

Rate Limits

API requests are rate-limited based on your plan. Monitor your usage at Usage Analytics.

Next Steps