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

  • Create files (POST /files via createFile)
  • Generate API JWTs (genToken)
  • Read file media bytes (GET getFile)
  • Sync query embeddings (createFile save=false)
  • 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 createFile / POST /files)

Typical integration flow

Your app
REST createFile (POST /files)
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.

Create file (POST /files)

REST · callable

Upload corpus media to a base from base64 bytes or a public http(s) URL. Storage finalize + processing create File, Visibility, and EmbeddingIndex rows in Dgraph.

Example
curl -sS -X POST 'https://us-central1-qaleb-x.cloudfunctions.net/createFile' \
  -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",
      "visibility": "public"
    }
  }'

# Or ingest a public image URL (server-side fetch; mimeType optional):
curl -sS -X POST 'https://us-central1-qaleb-x.cloudfunctions.net/createFile' \
  -H 'Authorization: Bearer YOUR_FIREBASE_ID_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "baseId": "<base-uuid>",
      "url": "https://images.example.com/catalog/product.jpg",
      "filename": "product.jpg",
      "visibility": "public",
      "prompt": "Describe the product, visible text, colors, and notable details.",
      "region": "eu"
    }
  }'
Response (abbreviated)
{
  "status": "success",
  "data": {
    "fileId": "0xabc…",
    "storagePath": "public/media/0xabc…/media/src/report.pdf",
    "path": "public/media/0xabc…/media/src/report.pdf",
    "visibility": "public",
    "bucket": "your-project.appspot.com",
    "embedModel": "GEM_2_768"
  }
}

Provide exactly one source: data containing raw base64 bytes (without a data-URL prefix) plus mimeType, or url pointing to a publicly accessible http/https file such as an image (mimeType optional and inferred from the response). Optional prompt controls how Media.content is described; omit it to use Organization.defContentPrompt when set, otherwise the system summary prompt. Optional region is us, eu, or asia for corpus object storage; omit region to store in us (America, lowest-cost). The product UI may auto-select the lowest-latency region; Location in the files table is inferred from the file URL. Processing is async (save defaults true). Subscribe (step 3) or query (step 2) to see status → completed. Private uploads require a payment method (visibility=private). For integrations after genToken, send Authorization: Bearer YOUR_API_JWT; baseId must be in the token bases claim.

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 createFile with save=false, or embed client-side then search.

Read media (preview/source)

REST · callable

Integrations fetch image/audio/video bytes from getFile after auth. The function checks permissions then streams the object body (not a redirect URL).

Example
curl -sS 'https://us-central1-qaleb-x.cloudfunctions.net/getFile?fileId=<file-uuid>&prev=true' \
  -H 'Authorization: Bearer YOUR_API_JWT' \
  -o preview.jpg
Response (abbreviated)
(binary response body — Content-Type: image/jpeg, etc.)

Use prev=false for the original file (media/src). When prev=true the server resolves preview paths and falls back to source if needed. Returns 401/403 when token is missing, expired, or file is outside token base scope.

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 defContentPrompt }
    }
  }
}

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