Capabilities

Vault

Projets, documents, uploads, interrogation d'ingestion et recherche hybride. Huit capabilities qui couvrent tout ce dont vous avez besoin pour gérer le store de documents Alloovium depuis votre propre backend.

Isolement de tenant

Propriété dérivée du principal

Chaque capability vault dérive le tenant propriétaire et l'utilisateur du principal authentifié — jamais des paramètres de requête. Une clé API créée sous le tenant A ne peut jamais voir les projets du tenant B, même en devinant les IDs. Les IDs inconnus ou inter-tenants retournent code, pas 403 — nous ne distinguons délibérément pas les deux cas pour que les attaquants ne puissent pas sonder l'espace d'ID.

vault.list_projects

GET/api/v2/vault/projects

Listez les projets accessibles à l'utilisateur de la clé API, les plus récents en premier.

scope: vault:readcost: 1

Requête

Paramètres de requête uniquement. Paginé par curseur — voir Pagination.

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

Réponse

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}

Retournez l'enregistrement de projet complet, incluant tenant_id, owner_id et timestamps.

scope: vault:readcost: 1

Requête

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

Réponse

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"
}

Les IDs de projet inconnus ou inter-tenants retournent code.

vault.create_project

POST/api/v2/vault/projects

Créez un nouveau projet dans le tenant de l'appelant. L'utilisateur de la clé API devient le propriétaire.

scope: vault:writecost: 2

Corps de requête

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

name est requis (1–255 caractères). Tous les autres champs sont optionnels. Attachez un header header — voir Idempotence.

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"}'

Réponse

Retourne la même enveloppe envelope que capability, avec un nouveau id.

Override de permission

Les utilisateurs marqués avec flag — une permission de niveau tenant — obtiendront code même avec scope dans le scope. Les admins d'organisation contournent cette vérification.

vault.list_documents

GET/api/v2/vault/documents

Listez les documents accessibles à l'utilisateur de la clé API. Filtrez optionnellement par projet ou dossier.

scope: vault:readcost: 1

Paramètres de requête

field — portée sur un projet (optionnel).
field — portée sur un dossier à l'intérieur d'un projet (optionnel).
field — curseur de pagination opaque (optionnel).
field — 1 à 100, défaut 25.

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

Réponse

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}

Récupérez l'enregistrement de document complet : nom de fichier, MIME, taille, nombre de pages, statut de traitement.

scope: vault:readcost: 1

Réponse

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

Uploadez un fichier et démarrez l'ingestion. Retourne un job_id que vous pouvez interroger ou corréler avec les Webhooks (futur).

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

Requête

Formulaire multipart avec deux champs : file (les octets) et project (le projet cible). Les fichiers au-dessus de la taille maximale retournent too_large, et les extensions non supportées retournent 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"

Réponse

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

field est null pendant que le job s'exécute. Interrogez capability jusqu'à ce que le job se termine, puis utilisez le field retourné avec capability.

Les clients MCP ne peuvent pas uploader des fichiers

Cette capability est REST uniquement. Les outils MCP qui offrent un transport JSON-RPC n'ont aucun moyen d'envoyer des pièces jointes binaires, donc l'upload est omis de la liste d'outils MCP. Si vous avez besoin qu'un agent ingère des fichiers, utilisez l'endpoint REST directement.

vault.get_ingestion_job

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

Interrogez un job d'upload pour sa progression, son achèvement et le document_id terminé.

scope: vault:readcost: 1

Requête

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

Réponse

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"
}

Les jobs inconnus, inter-tenants ou inaccessibles retournent code. Les jobs en échec gardent field comme null et remplissent error.

vault.search

POST/api/v2/vault/search

Récupération hybride BM25 + vecteur dense avec reclassement. Scopée au tenant, optionnellement à des projets ou documents spécifiques.

scope: vault:readcost: 5

Corps de requête

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

field — 1 à 1000 caractères. Requis.
field — 1 à 50, défaut 15. Nombre maximum de résultats classés à retourner.
field — liste blanche optionnelle. L'appelant doit avoir accès en vue à chacun.
field — liste blanche optionnelle pour une portée profonde.

Réponse

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
}

Préférez vault.search aux nombreux appels vault.get_document

La recherche coûte 5 tokens. Si vous avez besoin du contenu d'une poignée de documents, payer 5 une fois est mieux que payer 1 pour chaque get de document suivi de votre propre correspondance par mots-clés.

Voir aussi

Chat — posez des questions sur les documents vault avec des citations.
Workflows — exécutez des automations multi-étapes sur votre vault.