Quickstart

Get from zero to your first search result in under 5 minutes.

1. Create an Account

Sign up to get your API key:

cURL

curl -X POST https://api.useragex.com/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "password": "your-secure-password",
    "name": "Jane Developer"
  }'

TypeScript

// Sign up via the API, then use the returned API key
const res = await fetch('https://api.useragex.com/api/auth/signup', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'dev@example.com',
    password: 'your-secure-password',
    name: 'Jane Developer',
  }),
});

const { data } = await res.json();
console.log(data.api_key); // Save this — shown only once

Python

import httpx

res = httpx.post("https://api.useragex.com/api/auth/signup", json={
    "email": "dev@example.com",
    "password": "your-secure-password",
    "name": "Jane Developer",
})

data = res.json()["data"]
print(data["api_key"])  # Save this — shown only once

Save your api_key — it is shown only once. If you lose it, you can regenerate it from the dashboard.

2. Create a Knowledge Base

A knowledge base is a logical collection of documents. All searches are scoped to a single KB.

cURL

curl -X POST https://api.useragex.com/api/v1/knowledge-bases \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product Docs", "description": "All product documentation" }'

TypeScript

import { RAGClient } from '@rag-api/sdk';

const client = new RAGClient({ apiKey: 'YOUR_API_KEY' });

const kb = await client.createKnowledgeBase({
  name: 'Product Docs',
  description: 'All product documentation',
});

console.log(kb.id); // e.g. "kb_x1y2z3w4v5"

Python

from rag_api import RAGClient

client = RAGClient(api_key="YOUR_API_KEY")

kb = client.create_knowledge_base(
    name="Product Docs",
    description="All product documentation",
)

print(kb["id"])  # e.g. "kb_x1y2z3w4v5"

Note the id — you’ll use it in the next steps.

3. Upload a Document

Upload a file to your knowledge base. Processing happens asynchronously.

cURL

curl -X POST https://api.useragex.com/api/v1/knowledge-bases/KB_ID/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@product-guide.pdf" \
  -F 'metadata={"department": "engineering", "version": 2}'

TypeScript

import { readFileSync } from 'fs';

const file = new File(
  [readFileSync('product-guide.pdf')],
  'product-guide.pdf',
  { type: 'application/pdf' }
);

const doc = await client.uploadDocument(kb.id, file, {
  metadata: { department: 'engineering', version: 2 },
});

console.log(doc.status); // "pending"

Python

doc = client.upload_document(
    kb["id"],
    "product-guide.pdf",
    metadata={"department": "engineering", "version": 2},
)

print(doc["status"])  # "pending"

The document is returned immediately with status: "pending". It moves through: pending → parsing → chunking → embedding → ready.

Alternative: Ingest Raw Text

If you already have text content, skip the file upload:

cURL

curl -X POST https://api.useragex.com/api/v1/knowledge-bases/KB_ID/documents/text \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Machine learning is a subset of AI...",
    "name": "ml-notes.txt",
    "metadata": { "source": "api" }
  }'

TypeScript

const textDoc = await client.uploadTextDocument(kb.id, {
  text: 'Machine learning is a subset of AI...',
  name: 'ml-notes.txt',
  metadata: { source: 'api' },
});

Python

text_doc = client.upload_text_document(
    kb["id"],
    text="Machine learning is a subset of AI...",
    name="ml-notes.txt",
    metadata={"source": "api"},
)

4. Wait for Processing

Poll the document status until it reaches ready:

cURL

curl https://api.useragex.com/api/v1/knowledge-bases/KB_ID/documents/DOC_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

TypeScript

let status = doc.status;
while (status !== 'ready' && status !== 'failed') {
  await new Promise((r) => setTimeout(r, 2000));
  const updated = await client.getDocument(kb.id, doc.id);
  status = updated.status;
}

Python

import time

while doc["status"] not in ("ready", "failed"):
    time.sleep(2)
    doc = client.get_document(kb["id"], doc["id"])

5. Search

Run a natural language search against your knowledge base:

cURL

curl -X POST https://api.useragex.com/api/v1/knowledge-bases/KB_ID/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I configure authentication?",
    "top_k": 5,
    "rerank": true
  }'

TypeScript

const results = await client.search(kb.id, {
  query: 'How do I configure authentication?',
  top_k: 5,
});

console.log(results.results[0].text);
// "To configure authentication, navigate to Settings > Auth and enable..."

Python

results = client.search(
    kb["id"],
    query="How do I configure authentication?",
    top_k=5,
)

print(results["results"][0]["text"])
# "To configure authentication, navigate to Settings > Auth and enable..."

The response includes ranked chunks with relevance scores, chunk metadata (page numbers, section headings), and document metadata:

{
  "data": {
    "query": "How do I configure authentication?",
    "results": [
      {
        "chunk_id": "chk_k1l2m3n4o5",
        "document_id": "doc_f6g7h8i9j0",
        "document_name": "product-guide.pdf",
        "text": "To configure authentication, navigate to Settings > Auth and enable...",
        "score": 0.94,
        "metadata": {
          "chunk_index": 3,
          "start_page": 5,
          "end_page": 5,
          "section_heading": "Authentication Setup"
        },
        "document_metadata": {
          "department": "engineering",
          "version": 2
        }
      }
    ],
    "usage": {
      "embedding_tokens": 12,
      "rerank_applied": true,
      "chunks_searched": 34
    }
  }
}

Feed these results into your LLM as context — that’s RAG.

Next Steps

• Concepts: Search Pipeline — understand how search works under the hood
• Guide: Search & Filtering — metadata filters, score thresholds, reranking options
• Guide: Error Handling — error codes and retry strategies
• API Reference — full endpoint documentation
• TypeScript SDK | Python SDK — complete SDK reference