Docs
API

API reference

Base URL
https://api.cogniweave.com.au
Authentication
All /api/* endpoints (except the public lead form) require a Bearer token. Sign in to CogniWeave to obtain your access token, then send it as Authorization: Bearer <access_token>. Requests are automatically scoped to your workspace.
Content type
application/json, except file upload which uses multipart/form-data.

Making requests

Send your bearer token in the Authorization header. Here is the same agent query in two flavours:

cURL
curl https://api.cogniweave.com.au/api/agent/query \
  -H "Authorization: Bearer $COGNIWEAVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"question": "What are the payment terms in the Acme contract?"}'
JavaScript
const res = await fetch("https://api.cogniweave.com.au/api/agent/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ question: "What are the payment terms in the Acme contract?" }),
});
const data = await res.json();

Tenancy & isolation

Every CogniWeave account is its own isolated tenant. Your access token identifies your tenant, and every API request is automatically scoped to it — you can only read and write data that belongs to your own tenant, and there is no cross-tenant access.

The tenant your token belongs to is returned by GET /api/me as the tenant object (its id, slug, name, and your role within it). All Files, Ingestion jobs, Search, Agent, and Workspace settings endpoints operate only within your tenant. Data uploaded under one account is never visible to another.

Health

GET/health

Liveness and version.

cURL
curl https://api.cogniweave.com.au/health
Example response
{
  "ok": true,
  "version": "0.3.0",
  "control_plane": true
}

Identity

GET/api/me

The current user, their workspace, and role.

cURL
curl https://api.cogniweave.com.au/api/me \
  -H "Authorization: Bearer $TOKEN"
Example response
{
  "user": { "id": "uuid", "email": "you@example.com" },
  "tenant": {
    "id": "uuid",
    "slug": "default",
    "name": "Default",
    "role": "owner"
  },
  "is_platform_admin": false
}

role is one of: owner, admin, member, viewer. tenant may be null if no workspace is linked.

Files

POST/api/files/upload

Upload one or more files (multipart/form-data, field name "files"). Accepted extensions: .eml, .msg, .mbox, .pdf, .docx, .doc, .txt, .md, .rtf, .csv, .xlsx, .pptx, .png, .jpg, .jpeg, .webp, .tiff, .html, .json.

cURL
curl -X POST https://api.cogniweave.com.au/api/files/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "files=@report.pdf"
Example response
{
  "job_id": "uuid",
  "file_ids": ["uuid"]
}
GET/api/files

List files in your workspace.

cURL
curl https://api.cogniweave.com.au/api/files \
  -H "Authorization: Bearer $TOKEN"

Response: array of File objects (see shape below).

GET/api/files/{id}

Get one file.

cURL
curl https://api.cogniweave.com.au/api/files/FILE_ID \
  -H "Authorization: Bearer $TOKEN"

Response: File object.

DELETE/api/files/{id}

Delete a file.

cURL
curl -X DELETE https://api.cogniweave.com.au/api/files/FILE_ID \
  -H "Authorization: Bearer $TOKEN"
Example response
{ "ok": true }
POST/api/files/{id}/reprocess

Re-run ingestion for a file.

cURL
curl -X POST https://api.cogniweave.com.au/api/files/FILE_ID/reprocess \
  -H "Authorization: Bearer $TOKEN"
Example response
{ "job_id": "uuid" }
GET/api/files/{id}/download-url?expires_in=600

Get a temporary download URL.

cURL
curl "https://api.cogniweave.com.au/api/files/FILE_ID/download-url?expires_in=600" \
  -H "Authorization: Bearer $TOKEN"
Example response
{
  "url": "https://...",
  "expires_in": 600
}
File object shape
{
  "id": "uuid",
  "filename": "report.pdf",
  "source_type": "pdf",
  "status": "success",
  "uploaded_at": "ISO-8601",
  "processed_at": "ISO-8601 | null",
  "chunk_count": 12,
  "ocr_used": false,
  "parent_id": "uuid | null",
  "size_bytes": 84213,
  "warnings": [],
  "error": null
}

source_type enum: pdf, email, image, docx, csv, xlsx, pptx, html, txt, json, other.

status enum: queued, processing, success, failed, skipped.

Ingestion jobs

GET/api/ingestion/jobs

List recent ingestion jobs.

cURL
curl https://api.cogniweave.com.au/api/ingestion/jobs \
  -H "Authorization: Bearer $TOKEN"

Response: array of Job objects (see shape below).

GET/api/ingestion/jobs/{id}

Get one job.

cURL
curl https://api.cogniweave.com.au/api/ingestion/jobs/JOB_ID \
  -H "Authorization: Bearer $TOKEN"

Response: Job object.

Job object shape
{
  "id": "uuid",
  "status": "success",
  "total": 1,
  "succeeded": 1,
  "failed": 0,
  "current_step": null,
  "created_at": "ISO-8601",
  "finished_at": "ISO-8601 | null",
  "file_ids": ["uuid"],
  "errors": []
}

status enum: queued, running, success, failed, partial.

Search

POST/api/search

Direct hybrid retrieval over your memory.

cURL
curl -X POST https://api.cogniweave.com.au/api/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "string", "top_k": 20}'
Request body
{
  "query": "string",
  "top_k": 20
}

top_k is optional.

Example response
{
  "hits": [
    {
      "unit_id": "uuid",
      "file_id": "uuid",
      "file_title": "report.pdf",
      "source_type": "pdf",
      "snippet": "…matched text…",
      "final_score": 0.82,
      "semantic_score": 0.79,
      "lexical_score": 0.4,
      "symbolic_match": false,
      "page_number": 3,
      "date": "ISO-8601 | null"
    }
  ]
}

Agent

POST/api/agent/query

Ask a question; get a cited answer composed from your memory.

cURL
curl -X POST https://api.cogniweave.com.au/api/agent/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"question": "string", "include_citations": true}'
Request body
{
  "question": "string",
  "include_citations": true
}
Example response
{
  "answer": "…answer text with [1] style citations…",
  "citations": [
    {
      "unit_id": "uuid",
      "final_score": 0.82,
      "source_file_id": "uuid",
      "snippet": "…",
      "file_title": "report.pdf",
      "page_number": 3
    }
  ],
  "follow_ups": ["…suggested question…"],
  "limitations": "null or a note when memory is insufficient"
}

Workspace settings

GET/api/settings/workspace

Get workspace settings.

cURL
curl https://api.cogniweave.com.au/api/settings/workspace \
  -H "Authorization: Bearer $TOKEN"
Example response
{
  "ocr_enabled": true,
  "ocr_language": "eng",
  "chunk_size": 800,
  "chunk_overlap": 120
}
PUT/api/settings/workspace

Update workspace settings.

cURL
curl -X PUT https://api.cogniweave.com.au/api/settings/workspace \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ocr_enabled": true, "ocr_language": "eng", "chunk_size": 800, "chunk_overlap": 120}'
Request body
{
  "ocr_enabled": true,
  "ocr_language": "eng",
  "chunk_size": 800,
  "chunk_overlap": 120
}

Send any subset of the fields above. Response: the updated settings object.

Lead capture (public)

POST/api/public/leads

Public contact form; no authentication. Rate limited to 5 requests per minute per IP.

cURL
curl -X POST https://api.cogniweave.com.au/api/public/leads \
  -H "Content-Type: application/json" \
  -d '{"first_name": "string", "last_name": "string", "email": "string", "company": "string", "phone": "optional", "job_title": "optional", "message": "optional", "plan_interest": "optional"}'
Request body
{
  "first_name": "string",
  "last_name": "string",
  "email": "string",
  "company": "string",
  "phone": "optional",
  "job_title": "optional",
  "message": "optional",
  "plan_interest": "optional"
}
Example response
{ "ok": true, "lead_id": null }

Errors

All errors return JSON of the form { "detail": "message" }.

StatusMeaning
400invalid request
401missing or expired token
403no workspace, or not permitted
404not found
429too many requests
500server error