Integration Hub¶

Beyond Retrieval v2 exposes a standard REST API that any HTTP client can consume. Whether you are building a Python back-office script, a JavaScript front-end, an n8n workflow, or a Make.com scenario, the integration pattern is the same: authenticate, call JSON endpoints, and parse the response envelope.

Integration Architecture¶

graph LR
    subgraph Clients
        PY[Python / httpx]
        JS[JavaScript / fetch]
        CURL[curl / REST Client]
        N8N[n8n Workflow]
        MAKE[Make.com Scenario]
        OTHER[Any HTTP Client]
    end

    subgraph "Beyond Retrieval v2"
        API[FastAPI REST API]
        AUTH[Auth Middleware]
        RAG[RAG Pipeline]
        VEC[Vector Store]
        LLM[LLM Provider]
    end

    PY --> API
    JS --> API
    CURL --> API
    N8N --> API
    MAKE --> API
    OTHER --> API
    API --> AUTH
    AUTH --> RAG
    RAG --> VEC
    RAG --> LLM

Base URL¶

All endpoint paths in this documentation are relative to the base URL.

Authentication¶

Every request (except GET /api/health and GET /api/auth/config) requires a Bearer token in the Authorization header:

Authorization: Bearer <token>

Response Envelope¶

Every endpoint wraps its payload in a standard JSON envelope:

{
  "success": true,
  "data": { ... },
  "error": null
}

{
  "success": false,
  "data": null,
  "error": "Human-readable error message"
}

Content Types¶

Error Codes¶

API Sections Quick Reference¶

Integration Guides¶

Common Workflow¶

Regardless of language, the typical integration workflow follows these steps:

sequenceDiagram
    participant C as Client
    participant API as Beyond Retrieval API

    C->>API: POST /notebooks/ (create)
    API-->>C: notebook_id

    C->>API: POST /notebooks/{id}/documents/upload
    API-->>C: file metadata

    C->>API: POST /notebooks/{id}/documents/ingest
    API-->>C: job_id

    loop Poll until done
        C->>API: GET /notebooks/{id}/documents/{file_id}/stage
        API-->>C: status + progress
    end

    C->>API: POST /notebooks/{id}/conversations
    API-->>C: conversation_id

    C->>API: POST /notebooks/{id}/conversations/{conv_id}/messages
    API-->>C: AI response + citations

    C->>API: POST /notebooks/{id}/messages/{msg_id}/feedback
    API-->>C: feedback saved

1. Create a notebook -- the organizational container for your knowledge base
2. Upload files -- PDF, DOCX, TXT, CSV, XLSX, MD
3. Start ingestion -- parses, chunks, and embeds your documents
4. Poll for completion -- ingestion runs as a background task
5. Create a conversation -- a chat session within the notebook
6. Send messages -- the RAG pipeline retrieves context and generates answers
7. Submit feedback -- thumbs up/down for quality tracking