Developer API

API documentation

Illustrated guide to raggen.ai: when to call Firebase REST callables vs GraphQL queries and subscriptions—with copy-paste examples for upload, fetch, live updates, and topK search.

REST vs GraphQL

Two surfaces, one Dgraph backend. Choose REST for imperative actions; GraphQL for structured reads and live updates.

REST (Firebase callables)
https://us-central1-qaleb-x.cloudfunctions.net

Auth

Authorization: Bearer YOUR_TOKEN

Request body

{ "data": { …fields } }

Use for

  • Upload files to storage + enqueue indexing
  • Generate API JWTs (genToken)
  • Sync query embeddings (uploadMedia intent=query)
  • Read extracted file text (getFileContent)

Not the primary path for

  • Listing org files (use GraphQL query/subscription)
  • Live index updates (use GraphQL subscription)
  • Vector topK search (use GraphQL query)
GraphQL
https://api.raggen.ai/graphql

Auth

X-Auth-Token: YOUR_JWT

Request body

{ "query": "…", "variables": { … } }

Use for

  • Read org, bases, files, API keys
  • Subscribe to live file/org updates
  • TopK vector similarity (querySimilarEmbeddingIndexByEmbedding)
  • Mutations: addBase, updateUser, manage API keys

Not the primary path for

  • Binary file upload (use REST uploadMedia)

Typical integration flow

Your app
REST uploadMedia
Storage + Dgraph
GraphQL query / sub
Live UI / API

REST for writes and uploads · GraphQL for reads, search, and subscriptions

End-to-end by example

Upload a corpus file, read it once or subscribe for live status, then run topK vector search with a query embedding.

Submit a file (REST)

REST · callable

Upload corpus media to a base. Storage finalize + processing create File and EmbeddingIndex rows in Dgraph.

Example
curl -sS -X POST 'https://us-central1-qaleb-x.cloudfunctions.net/uploadMedia' \
  -H 'Authorization: Bearer YOUR_FIREBASE_ID_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "baseId": "<base-uuid>",
      "data": "<base64-bytes>",
      "mimeType": "application/pdf",
      "filename": "report.pdf",
      "intent": "corpus"
    }
  }'
Response (abbreviated)
{
  "status": "success",
  "data": {
    "fileId": "0xabc…",
    "path": "media/src/…",
    "bucket": "your-project.appspot.com",
    "embedModel": "GEM_2_768"
  }
}

Processing is async for intent=corpus. Subscribe (step 3) or query (step 2) to see status → completed.

Fetch files once (GraphQL query)

GraphQL · query

One-shot read of org files and metadata. Use after upload or for backfills.

Example
curl -sS -X POST 'https://api.raggen.ai/graphql' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-Token: YOUR_API_JWT' \
  -d '{
    "query": "query OrgFiles($id: ID!) { getOrganization(id: $id) { id name files { id name status type bytes bases { id name } } } }",
    "variables": { "id": "<org-uuid>" }
  }'
Response (abbreviated)
{
  "data": {
    "getOrganization": {
      "files": [
        { "id": "0xabc…", "name": "report.pdf", "status": "completed" }
      ]
    }
  }
}

Live updates (GraphQL subscription)

GraphQL · subscription

Same shape as the query, but pushed when embeddings finish or files change—what the dashboard uses.

Example
subscription OnFileUpdate($orgId: ID!) {
  getOrganization(id: $orgId) {
    id
    files {
      id
      name
      status
      embeddings { id model }
      bases { id name }
    }
  }
}

Connect over WebSocket to the GraphQL subscriptions URL (same host as HTTP). Apollo Client handles this in the app.

TopK similarity search (GraphQL)

GraphQL · query

Pass a query vector + topK; filter by embed model. Returns ranked hits with vector_distance.

Example
curl -sS -X POST 'https://api.raggen.ai/graphql' \
  -H 'Content-Type: application/json' \
  -H 'X-Auth-Token: YOUR_API_JWT' \
  -d '{
    "query": "query FilesWithinDistance($vector: [Float!]!, $topK: Int!, $filter: EmbeddingIndexFilter!) { querySimilarEmbeddingIndexByEmbedding(vector: $vector topK: $topK by: embedding filter: $filter) { id vector_distance file { id name } } }",
    "variables": {
      "vector": [0.01, -0.02, …],
      "topK": 10,
      "filter": { "model": { "eq": "GEM_2_768" } }
    }
  }'
Response (abbreviated)
{
  "data": {
    "querySimilarEmbeddingIndexByEmbedding": [
      { "vector_distance": 0.12, "file": { "id": "0x…", "name": "report.pdf" } }
    ]
  }
}

Obtain the query vector via REST uploadMedia with intent=query, or embed client-side then search.

Common operations

Copy-paste starting points for org setup, bases, files, API keys, and vector search prep.

Organizations for signed-in user

subscription

Traverse credentials → organization (org selector pattern).

GraphQL
subscription OnOrgsUpdate($email: String!) {
  getUser(email: $email) {
    credentials {
      active
      organization { id name type defEmbedModel }
    }
  }
}

List knowledge bases

query

All bases visible to the authenticated API token.

GraphQL
query GetBases {
  queryBase {
    id
    name
    description
    files { id name status }
    organization { id name }
  }
}

Single file by ID

query

Filter queryFile by id for metadata and extracted content.

GraphQL
query FileById($id: ID!) {
  queryFile(filter: { id: { eq: $id } }) {
    id
    name
    status
    content
    storageUrl
    prevUrl
    embeddings { id model }
    bases { id name }
  }
}

API keys for an org

query

List JWT scopes (bases) for automation and MCP.

GraphQL
query OrgApiKeys($orgId: ID!) {
  getOrganization(id: $orgId) {
    apiKeys { name apiKey bases { id name } }
  }
}

Interactive GraphQL IDE

Explore the schema, run queries, and test subscriptions. Sign in from the app to use protected operations with your session token.

GraphiQL
Connected to https://api.raggen.ai/graphql