API Reference v1.0

Build with
ZuqoAI Semantics

Integrate advanced semantic memory, vector embeddings, and contextual reasoning into your applications with our robust developer API.

Our Postman collection is available at
PostmanPostman Collection

REST Standards

Standard RESTful endpoints with predictable HTTP response codes.

Secure Auth

API Key based authentication for maximum security and ease of use.

Ultra Low Latency

Built on top of specialized vector engines for instant retrieval.

Embedding Models

fast-384

384d

Ultra-fast processing, ideal for quick embeddings

Fastest

accurate-768

768d

Highest accuracy for semantic understanding

Medium

multilingual-768

768d

Supports 50+ languages for global applications

Medium

fast-768

768d

768-dim embeddings with faster processing

Fast

Core AI Engine

POST/api/v1/embed

Embed Single

Generate a vector embedding for a single string of text.

Parameters

textRequired
stringThe text to encode.
model
stringModel alias (e.g., fast-384, accurate-768, multilingual-768, fast-768).
store
booleanWhether to persist in vector memory.

Interface Example

curl -X POST https://app.zuqolab.com/api/v1/embed \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The future of AI is semantic.",
    "model": "fast-384"
  }'
POST/api/v1/embed-batch

Batch Embeddings

Generate embeddings for an array of strings in a single request.

Parameters

textsRequired
string[]Array of text strings.
model
stringModel alias.

Interface Example

curl -X POST https://app.zuqolab.com/api/v1/embed-batch \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": ["First text", "Second text"],
    "model": "fast-384"
  }'
POST/api/v1/similarity

Compute Similarity

Compare two pieces of text and return a similarity score (0 to 1).

Parameters

text1Required
stringFirst text string.
text2Required
stringSecond text string.
model
stringModel alias for embedding.

Interface Example

curl -X POST https://app.zuqolab.com/api/v1/similarity \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text1": "Hello world",
    "text2": "Hi world"
  }'
POST/api/v1/search

Vector Search

Perform a semantic search against your persisted items.

Parameters

queryRequired
stringThe search query.
top_k
integerNumber of results to return.
filters
objectMetadata filters.

Interface Example

curl -X POST https://app.zuqolab.com/api/v1/search \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "financial reports",
    "top_k": 5
  }'
POST/api/v1/retrieve

RAG Retrieval

Get relevant context fragments for RAG pipelines.

Parameters

queryRequired
stringContext query.
top_k
integerNumber of fragments.

Interface Example

curl -X POST https://app.zuqolab.com/api/v1/retrieve \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is ZuqoAI?",
    "top_k": 3
  }'
POST/api/v1/extract-text

Extract Text (OCR)

Extract text from images or PDF files using advanced OCR.

Parameters

fileRequired
fileImage/PDF file to process.
format
string'text' or 'markdown'.

Interface Example

curl -X POST https://app.zuqolab.com/api/v1/extract-text \
  -H "X-API-KEY: YOUR_API_KEY" \
  -F "file=@document.pdf"
POST/api/v1/chat

Chat Completion

Engage with the LUNA model using an OpenAI-compatible messages array.

Parameters

messagesRequired
arrayList of message objects (role, content).
model
stringModel alias (e.g., luna-3, luna-mini).
temperature
floatCreativity bias.

Interface Example

curl -X POST https://app.zuqolab.com/api/v1/chat \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Explain quantum physics in one sentence."}
    ],
    "model": "luna-3"
  }'
GET/api/v1/models

List Models

Get a list of all available model aliases and their capabilities.

Interface Example

curl -H "X-API-KEY: YOUR_API_KEY" https://app.zuqolab.com/api/v1/models

AI Data Factory

POST/api/v1/dataset/generate

Generate Dataset

Trigger synthetic dataset generation based on a prompt template.

Parameters

nameRequired
stringName of the generation task.
prompt_templateRequired
stringExample: 'Generate Q&A for...'
count
integerNumber of rows to generate.

Interface Example

curl -X POST https://app.zuqolab.com/api/v1/dataset/generate \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FAQ Generation",
    "prompt_template": "Generate questions about our refund policy.",
    "count": 20
  }'
GET/api/v1/dataset/training-data

List Training Data

Retrieve generated synthetic data items.

Parameters

status
string'pending', 'approved', 'rejected'.

Interface Example

curl -H "X-API-KEY: YOUR_API_KEY" https://app.zuqolab.com/api/v1/dataset/training-data
POST/api/v1/dataset/training-data/{id}/save-to-rag

Save to RAG

Move an approved training data item into the production vector store.

Interface Example

curl -X POST https://app.zuqolab.com/api/v1/dataset/training-data/123/save-to-rag \
  -H "X-API-KEY: YOUR_API_KEY"
POST/api/v1/dataset/versions

Create Snapshot

Create a named version snapshot of your current state.

Parameters

nameRequired
stringVersion name (e.g. v1.0.0).

Interface Example

curl -X POST https://app.zuqolab.com/api/v1/dataset/versions?name=v1.0.0 \
  -H "X-API-KEY: YOUR_API_KEY"

Data Management

GET/api/v1/items

List Items

Paginate through your persisted vector items.

Parameters

skip
integerOffset.
limit
integerFetch count.

Interface Example

curl -H "X-API-KEY: YOUR_API_KEY" "https://app.zuqolab.com/api/v1/items?limit=10"
POST/api/v1/items

Create Item

Manually insert a text item into the vector store.

Parameters

textRequired
stringContent.
metadata
objectKey-value pairs.

Interface Example

curl -X POST https://app.zuqolab.com/api/v1/items \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Manual entry content.",
    "metadata": {"source": "manual"}
  }'
GET/api/v1/jobs/{id}

Job Status

Check the status of a background bulk ingestion or generation job.

Interface Example

curl -H "X-API-KEY: YOUR_API_KEY" https://app.zuqolab.com/api/v1/jobs/JOB_ID

Keys & Usage

GET/api/v1/keys

List API Keys

Read all active API keys for your account.

Interface Example

curl -H "X-API-KEY: YOUR_API_KEY" https://app.zuqolab.com/api/v1/keys
GET/api/v1/me

Account Profile

Retrieve details about your account, active plan, and owner info.

Interface Example

curl -H "X-API-KEY: YOUR_API_KEY" https://app.zuqolab.com/api/v1/me
GET/api/v1/usage

Usage Stats

Get real-time statistics on requests, embeddings, and credits used.

Interface Example

curl -H "X-API-KEY: YOUR_API_KEY" https://app.zuqolab.com/api/v1/usage
PUT/api/v1/webhook-settings

Webhook Settings

Configure URL for real-time notifications on job completion.

Parameters

webhook_urlRequired
stringTarget URL.

Interface Example

curl -X PUT https://app.zuqolab.com/api/v1/webhook-settings \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://callback.io/webhooks"}'