Capabilities

Vault

Projects, documents, uploads, ingestion polling, and hybrid search. Eight capabilities that cover everything you need to manage Alloovium's document store from your own backend.

Tenant isolation

Principal-derived ownership

Every vault capability derives the owning tenant and user from the authenticated principal — never from request parameters. An API key created under tenant A can never see tenant B's projects, even by guessing IDs. Unknown or cross-tenant IDs return code, not 403 — we deliberately do not distinguish the two cases so attackers cannot probe ID space.

vault.list_projects

GET/api/v2/vault/projects

List projects accessible to the API key's user, newest first.

scope: vault:readcost: 1

Request

Query parameters only. Cursor-paginated — see Pagination.

bash
curl -sS "https://api.alloovium.com/api/v2/vault/projects?limit=25" \
  -H "Authorization: Bearer $ALLOOVIUM_API_KEY"

Response

json
{
  "data": [
    {
      "id": "8f2e3c1a-...",
      "name": "Downtown Tower",
      "description": "Mixed-use high-rise.",
      "project_type": "commercial",
      "status": "active",
      "created_at": "2026-04-02T10:12:34+00:00"
    }
  ],
  "next_cursor": "eyJjcmVhdGVkX2F0Ij...",
  "has_more": true
}

vault.get_project

GET/api/v2/vault/projects/{project_id}

Return the full project record, including tenant_id, owner_id, and timestamps.

scope: vault:readcost: 1

Request

bash
curl -sS "https://api.alloovium.com/api/v2/vault/projects/8f2e3c1a-..." \
  -H "Authorization: Bearer $ALLOOVIUM_API_KEY"

Response

json
{
  "id": "8f2e3c1a-...",
  "tenant_id": "c7a1e9c2-...",
  "owner_id": "1f02d9ef-...",
  "name": "Downtown Tower",
  "description": "Mixed-use high-rise.",
  "project_type": "commercial",
  "project_phase": "design",
  "location": "Sydney CBD",
  "scope": "Full architectural + structural.",
  "status": "active",
  "created_at": "2026-04-02T10:12:34+00:00",
  "updated_at": "2026-04-05T14:22:08+00:00"
}

Unknown or cross-tenant project IDs return code.

vault.create_project

POST/api/v2/vault/projects

Create a new project in the caller's tenant. The API key's user becomes the owner.

scope: vault:writecost: 2

Request body

json
{
  "name": "Downtown Tower",
  "description": "Mixed-use high-rise.",
  "project_type": "commercial",
  "location": "Sydney CBD"
}

name is required (1–255 chars). All other fields are optional. Attach an header header — see Idempotency.

bash
curl -sS https://api.alloovium.com/api/v2/vault/projects \
  -H "Authorization: Bearer $ALLOOVIUM_API_KEY" \
  -H "Idempotency-Key: create-tower-2026-04-08" \
  -H "Content-Type: application/json" \
  -d '{"name": "Downtown Tower", "project_type": "commercial"}'

Response

Returns the same envelope envelope as capability, with a fresh id.

Permission override

Users flagged with flag — a tenant-level permission — will get code even with scope in scope. Org admins bypass this check.

vault.list_documents

GET/api/v2/vault/documents

List documents accessible to the API key's user. Optionally filter by project or folder.

scope: vault:readcost: 1

Query parameters

field — scope to one project (optional).
field — scope to one folder inside a project (optional).
field — opaque pagination cursor (optional).
field — 1 to 100, default 25.

bash
curl -sS "https://api.alloovium.com/api/v2/vault/documents?project_id=8f2e3c1a-...&limit=50" \
  -H "Authorization: Bearer $ALLOOVIUM_API_KEY"

Response

json
{
  "data": [
    {
      "id": "4a1c2b3d-...",
      "filename": "Lobby_Spec.pdf",
      "file_type": "pdf",
      "file_size": 204856,
      "status": "processed",
      "project_id": "8f2e3c1a-...",
      "folder_id": null,
      "created_at": "2026-04-03T09:10:00+00:00"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

vault.get_document

GET/api/v2/vault/documents/{document_id}

Fetch the full document record: filename, MIME, size, page count, processing status.

scope: vault:readcost: 1

Response

json
{
  "id": "4a1c2b3d-...",
  "tenant_id": "c7a1e9c2-...",
  "filename": "Lobby_Spec.pdf",
  "file_type": "pdf",
  "file_size": 204856,
  "mime_type": "application/pdf",
  "status": "processed",
  "title": "Lobby Specification — Downtown Tower",
  "page_count": 42,
  "word_count": 18412,
  "project_id": "8f2e3c1a-...",
  "folder_id": null,
  "created_at": "2026-04-03T09:10:00+00:00"
}

vault.upload_document

POST/api/v2/vault/documents

Upload a file and kick off ingestion. Returns a job_id you can poll or correlate with Webhooks (future).

scope: vault:writecost: 10multipart/form-data

Request

Multipart form with two fields: file (the bytes) and project (the target project). Files above the maximum size return too_large, and unsupported extensions return unsupported.

bash
curl -sS https://api.alloovium.com/api/v2/vault/documents \
  -H "Authorization: Bearer $ALLOOVIUM_API_KEY" \
  -F "project_id=8f2e3c1a-..." \
  -F "file=@./Lobby_Spec.pdf"

Response

json
{
  "job_id": "c1d2e3f4-...",
  "document_id": null,
  "status": "pending"
}

field is null while the job is running. Poll capability until the job completes, then use the returned field with capability.

MCP clients cannot upload files

This capability is REST-only. MCP tools that offer JSON-RPC transport have no way to send binary attachments, so upload is omitted from the MCP tool list. If you need an agent to ingest files, use the REST endpoint directly.

vault.get_ingestion_job

GET/api/v2/vault/ingestion-jobs/{job_id}

Poll an upload job for progress, completion, and the finished document_id.

scope: vault:readcost: 1

Request

bash
curl -sS "https://api.alloovium.com/api/v2/vault/ingestion-jobs/c1d2e3f4-..." \
  -H "Authorization: Bearer $ALLOOVIUM_API_KEY"

Response

json
{
  "job_id": "c1d2e3f4-...",
  "project_id": "8f2e3c1a-...",
  "document_id": "4a1c2b3d-...",
  "original_filename": "Lobby_Spec.pdf",
  "file_size": 204856,
  "mime_type": "application/pdf",
  "status": "completed",
  "progress": {
    "total_pages": 42,
    "pages_read": 42,
    "pages_ocr": 0,
    "chunks_created": 118,
    "chunks_indexed": 118,
    "current_step": "completed"
  },
  "total_chunks": 118,
  "processing_time_ms": 9412,
  "error_message": null,
  "retry_count": 0,
  "created_at": "2026-04-03T09:10:00+00:00",
  "started_at": "2026-04-03T09:10:02+00:00",
  "completed_at": "2026-04-03T09:10:11+00:00"
}

Unknown, cross-tenant, or inaccessible jobs return code. Failed jobs keep field as null and populate error.

vault.search

POST/api/v2/vault/search

Hybrid BM25 + dense vector retrieval with reranking. Scoped to the tenant, optionally to specific projects or documents.

scope: vault:readcost: 5

Request body

json
{
  "query": "What's the fire rating on the level-3 lobby walls?",
  "k": 10,
  "project_ids": ["8f2e3c1a-..."],
  "document_ids": null
}

field — 1 to 1000 characters. Required.
field — 1 to 50, default 15. Maximum ranked results to return.
field — optional whitelist. Caller must have view access to each.
field — optional whitelist for deep scoping.

Response

json
{
  "results": [
    {
      "chunk_id": "7b3e1a...",
      "document_id": "4a1c2b3d-...",
      "content": "Level-3 lobby walls carry a 90-minute fire rating per AS 1530.4...",
      "score": 0.9142,
      "document_title": "Lobby Specification — Downtown Tower",
      "filename": "Lobby_Spec.pdf",
      "page_number": 14,
      "chunk_index": 27,
      "highlights": ["90-minute fire rating", "AS 1530.4"]
    }
  ],
  "total_time_ms": 187
}

Prefer vault.search over many vault.get_document calls

Search is 5 tokens. If you need the content of a handful of documents, paying 5 once beats paying 1 for each document get followed by your own keyword matching.

Vault

Tenant isolation

vault.list_projects

Request

Response

vault.get_project

Request

Response

vault.create_project

Request body

Response

vault.list_documents

Query parameters

Response

vault.get_document

Response

vault.upload_document

Request

Response

vault.get_ingestion_job

Request

Response

vault.search

Request body

Response

See also