HTTP API reference

Endpoints for searching, asking a question, managing sources, uploading documents and reading instance information. The same API serves Proxyma Desktop, the Home Server and Proxyma Enterprise Server. Authentication differs, the token endpoints exist only on Proxyma Enterprise Server, and the upload endpoints only on the Home Server and Proxyma Enterprise Server.

Before you start

Authentication

Proxyma Desktop and the Home Server have no accounts. Every endpoint below answers an unauthenticated call, so keep them reachable only from a machine or network you control - see the Home Server guide.

Proxyma Enterprise Server has accounts. Without a token, search and chat (where guest chat is enabled) see shared sources only, and the source, upload and token endpoints return 401. Send a token to include your own sources:

-H "Authorization: Bearer <your-token>"

A token has the permissions of the account that created it and never more.

Getting a token

On Proxyma Enterprise Server, create one in Settings → API Tokens, or over the API with the session token of a signed-in browser (its PROXYMA-TOKEN cookie). An MCP token cannot create tokens.

curl -X POST https://your-proxyma-host/api/v1/settings/mcp-tokens \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-session-token>" \
  -d '{"label": "ci-pipeline"}'

The raw token is pxm_ followed by 64 hex characters and is returned once, at creation, in the token field. Add "expiresInDays" of 30, 60, 90 or 180 to make it expire. A lost token cannot be recovered - revoke it and create another. GET the same path to list tokens (only their first few characters are shown), and DELETE /api/v1/settings/mcp-tokens/{id} to revoke one.

Errors

400 for a malformed body or a value the server rejects, 401 when a call needs a session it does not have, 403 when your role or license tier does not allow the call, 404 for an unknown id, 429 when a rate limit or quota is reached. Another user's source answers 400, not 403. A failure body is usually JSON with a detail or error field, and is sometimes empty.

Unknown fields in a request body are ignored, not rejected. A misspelled parameter returns 200 and the default is used.

Search

Returns matching passages with their sources, using the same keyword and vector search as chat. It sends the query to your embedding provider, and to a model as well when query expansion or reranking is on, but writes no answer - so it costs far less than asking a question.

POST /api/v1/search

Example

curl -X POST https://your-proxyma-host/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication flow", "topK": 5, "minScore": 0.4}'

Response

{
  "query": "authentication flow",
  "totalResults": 2,
  "results": [
    {
      "id": "a3f1c2e4-...",
      "title": "Authentication design",
      "snippet": "The auth module handles JWT...",
      "sourceUrl": "https://confluence.example.com/display/PROJ/auth-design",
      "connectorType": "confluence",
      "score": 0.87
    }
  ]
}

Asking a question

Returns an answer produced by the agent. It is billed by the instance's AI provider and takes as long as the model takes.

POST /api/v1/chat

curl -X POST https://your-proxyma-host/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Which open bugs mention the trap handler?"}'

{"conversationId": "7c9e6679-..."}

GET /api/v1/chat/events/{conversationId}

A text/event-stream carrying the turn as it runs. Open it after posting the message: it replays the turn from its first event, and a stream opened before the post receives nothing from that turn. A keepalive comment is sent every 15 seconds.

Every event is named chat, and its data is JSON with type, callId, toolName, data and parentCallId. type is one of:

curl -N https://your-proxyma-host/api/v1/chat/events/7c9e6679-...

Sources

A source is one indexed item - a folder, a Jira project, a website, a Confluence space. Source endpoints are under /api/v1/indexing.

GET /api/v1/indexing/summary

Totals plus a capped preview of each type. On Proxyma Enterprise Server, add ?includeShared=true to count shared sources as well as your own.

curl https://your-proxyma-host/api/v1/indexing/summary

{
  "totalSources": 12,
  "totalDocs": 3480,
  "activeIndexingCount": 0,
  "byType": {
    "confluence": { "total": 3, "preview": [ ... ] }
  }
}

activeIndexingCount counts documents being downloaded, converted or embedded right now.

GET /api/v1/indexing/by-type/{type}

Sources of one type - files, webpage, jira, confluence, bitbucket, svn, networkshare, sharepoint, teams, teamschat, outlook, or all. Add ?q= to filter by name. Results come a page at a time: pass page and size (at most 100).

POST /api/v1/indexing/{id}/sync

Start a sync now. Returns {"started": true}, or false if a sync is already running; a second one is not queued. A manual sync is always a full sync, so it also picks up upstream deletions - unless it finds fewer than half the items the source had, in which case nothing is removed.

POST /api/v1/indexing/{id}/reindex

Rebuild the source from scratch. Use it after changing the embedding model; a plain sync keeps existing vectors. The source stays searchable during the rebuild. After a model change on Proxyma Desktop or the Home Server, the old index is kept until the new one is complete.

GET /api/v1/indexing/{id}/items

The documents in one source that are not being processed right now, with their indexing status, up to size (at most 200) at a time. Failed documents come first, then the most recently updated; pass the returned nextCursorFailed, nextCursorTouched and nextCursorId back as cursorFailed, cursorTouched and cursorId for the next page. /items/active returns those being processed now. /items/{documentId}/reindex re-indexes one document, answering 409 if it is being processed at that moment. Only the source's owner may call it. /items/{documentId}/preview returns {"chunks": [...]}, the indexed text search sees.

Changing and removing

Uploading documents

Add documents to the Home Server and Proxyma Enterprise Server by upload. Then register a folder of uploads as a source with POST /api/v1/files/folders/register and a body of {"folder": "policies"}.

POST /api/v1/files

multipart/form-data. 200 MB per file.

curl -X POST https://your-proxyma-host/api/v1/files \
  -F "file=@handbook.pdf" \
  -F "folder=policies"

{
  "id": "b12f...",
  "originalName": "handbook.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 481923,
  "uploadedAt": "2026-09-13T10:04:11Z"
}

Listing, quota and deleting

Instance information

GET /api/v1/health

Whether the instance is up, and what it is. Needs no authentication, returns nothing sensitive, and is the endpoint to point a monitor at.

curl https://your-proxyma-host/api/v1/health

{
  "status": "ok",
  "edition": "Desktop",
  "version": "0.33.0",
  "platform": "windows",
  "uptimeSeconds": 92,
  "uptime": "1m 32s"
}

These six fields are the whole response and are meant to stay that way, so a check written against it keeps working.

GET /api/v1/config

How the web interface is configured: branding, which features this deployment offers, and how documents get in. Needs no authentication and returns nothing sensitive.

It is not the health check - use GET /api/v1/health for that. This one carries whatever the interface needs and changes shape as the interface does.

curl https://your-proxyma-host/api/v1/config

{
  "version": "0.33.0",
  "serverPort": 4246,
  "platform": "linux",
  "orgMode": false,
  "orgCredentialConfigured": false,
  "branding": { "productName": "Proxyma", "faviconUrl": "/favicon.svg" },
  "fileUpload": true,
  "homeServer": false
}

orgMode and orgCredentialConfigured are not in use, and orgMode does not tell you whether a deployment has accounts.

MCP

To let an AI assistant search your sources itself, use the Model Context Protocol server instead. See MCP setup for Claude Code, GitHub Copilot and other clients.