Developer API¶

The Developer API lets external applications query your notebooks and run RAG-powered conversations using simple API keys — no JWT authentication required. Each key is scoped to a single notebook with configurable rate limits and optional expiry.

Base path: /api/v1/external Authentication: X-API-Key header Rate limiting: Per-key, configurable (default 100/hour)

How It Works¶

sequenceDiagram
    participant Admin as Admin User
    participant UI as Beyond Retrieval UI
    participant DB as Database
    participant Ext as External App
    participant API as External API

    Admin->>UI: Create API key for notebook
    UI->>DB: Store key_hash (SHA-256)
    UI-->>Admin: Show full key ONCE (br_key_...)

    Ext->>API: POST /query or /chat + X-API-Key header
    API->>DB: Validate key hash, check active/expiry
    API->>API: Execute RAG pipeline
    API-->>Ext: JSON response with chunks/answer

1. Admin creates an API key in the Developer API page (admin-only)
2. The full key is shown once — copy it immediately
3. External apps send requests with the key in the X-API-Key header
4. Each request is validated, rate-limited, and scoped to the key's notebook

Authentication¶

All external API endpoints require the X-API-Key header:

X-API-Key: br_key_Oq8vceZRJobUzknlT58_3CqhS2NLAQaqKfxqoYbZW0A

Error responses¶

Endpoints¶

E1: RAG Query¶

Retrieve relevant document chunks from the key's notebook without generating an AI answer.

POST /api/v1/external/query

Request parameters¶

Available strategies:

Request example¶

{
  "query": "What is the refund policy?",
  "strategy_id": "fusion",
  "top_k": 5
}

Response¶

{
  "success": true,
  "data": {
    "query": "What is the refund policy?",
    "strategy_id": "fusion",
    "chunks": [
      {
        "content": "Refunds are processed within 14 business days...",
        "source": "company-handbook.pdf",
        "score": 1.0,
        "metadata": {
          "file_id": "a1b2c3d4-...",
          "file_title": "company-handbook.pdf",
          "chunk_index": 12,
          "notebook_id": "...",
          "loc": { "lines": { "from": 45, "to": 62 } }
        }
      }
    ],
    "total_results": 5,
    "execution_time_ms": 1250.3
  },
  "error": null
}

Response fields¶

E2: Chat¶

Send a message and receive a RAG-powered AI response with citations. Conversations are automatically created if no conversation_id is provided, enabling both one-shot and multi-turn use cases.

POST /api/v1/external/chat

Request parameters¶

Available personas:

Supported languages:

Request example — single message¶

{
  "message": "What are the key benefits of the premium plan?",
  "persona": "professional",
  "language": "en"
}

Request example — multi-turn conversation¶

{
  "message": "Can you explain the pricing in more detail?",
  "conversation_id": "34f512ec-7f8a-4e6f-b8a0-38f1c143807d",
  "persona": "professional",
  "language": "en"
}

Response¶

{
  "success": true,
  "data": {
    "conversation_id": "34f512ec-7f8a-4e6f-b8a0-38f1c143807d",
    "answer": "The premium plan includes several key benefits:\n\n1. **Unlimited access** to all partner locations [1]\n2. **Online courses** including live sessions [2]\n3. **20% discount** for the first two months [3]\n\nMembers can manage everything through the mobile app.",
    "citations": [
      {
        "citation_id": 1,
        "content": "In your membership, access to all partner locations is included...",
        "file_name": "membership-guide.pdf",
        "similarity": 1.0
      },
      {
        "citation_id": 2,
        "content": "Online and live courses are included in every membership plan...",
        "file_name": "membership-guide.pdf",
        "similarity": 0.87
      }
    ],
    "suggested_questions": [
      "How do I cancel my membership?",
      "What payment methods are accepted?",
      "Is there a family plan available?"
    ],
    "is_cached": false,
    "execution_time_ms": 12500.0
  },
  "error": null
}

Response fields¶

E3: Conversation History¶

Retrieve all messages in a conversation. The conversation must belong to the API key's notebook.

GET /api/v1/external/chat/{conversation_id}/messages

Path parameters¶

Response¶

{
  "success": true,
  "data": {
    "conversation_id": "34f512ec-7f8a-4e6f-b8a0-38f1c143807d",
    "messages": [
      {
        "role": "user",
        "content": "What are the key benefits?",
        "created_at": "2026-03-04T09:46:37.125916Z"
      },
      {
        "role": "assistant",
        "content": "The key benefits include...",
        "created_at": "2026-03-04T09:46:47.476795Z"
      }
    ]
  },
  "error": null
}

Response fields¶

Error responses¶

Settings Inheritance¶

When optional parameters (strategy_id, top_k, persona, language) are omitted from a request, the API automatically uses the notebook's Intelligence Settings configured by the admin. This means external integrations get the same behavior as the built-in chat UI without needing to specify every parameter.

Additionally, the query endpoint passes the notebook's retrieval weights (full_text_weight, semantic_weight, rrf_k, rerank_top_k) to the retrieval pipeline automatically.

When a parameter is provided in the request, it overrides the notebook setting. This is fully backward-compatible: existing integrations that send explicit values will continue to work identically.

Admin Key Management¶

These endpoints require JWT authentication (admin-only). They are used by the Beyond Retrieval admin UI to manage API keys.

Create key request¶

{
  "notebook_id": "505b1a5c-b548-4089-8e37-63da42ee3c84",
  "name": "My Chatbot Key",
  "rate_limit": "100/hour",
  "expires_at": "2026-12-31T00:00:00Z"
}

Rate limit format¶

Rate limits follow the pattern <number>/<period>:

Configuration¶

Environment variables that control the Developer API: