Capabilities

Templates

Uploadez un template DOCX et laissez Alloovium le remplir depuis votre vault. Deux capabilities : démarrez un job de remplissage, puis interrogez-le jusqu'à ce que le document rempli soit prêt à télécharger.

Cycle de vie

Les remplissages de template sont asynchrones. Chaque remplissage suit le même schéma en quatre étapes :

POST le template DOCX (plus une portée optionnelle) à capability.
Obtenez un field. Le job démarre dans l'état state.
Interrogez capability toutes les 2–5 secondes.
Quand condition, téléchargez le résultat depuis field.

Même forme que les workflows

Les jobs de remplissage et les exécutions de workflow partagent la même machine d'état asynchrone (states). Si vous avez déjà écrit un interrogateur pour l'un, vous pouvez le réutiliser pour l'autre.

templates.start_fill

POST/api/v2/templates/fill

Uploadez un template DOCX et démarrez un job de remplissage. Retourne un job_id que vous interrogez pour le statut.

scope: templates:writecost: 25multipart/form-data

Requête

Formulaire multipart avec jusqu'à trois champs : file (requis — les octets DOCX), project (optionnel — portée de la source sur un seul projet) et docs (optionnel — liste UUID séparée par des virgules pour une portée profonde vers des documents spécifiques).

bash
curl -sS https://api.alloovium.com/api/v2/templates/fill \
  -H "Authorization: Bearer $ALLOOVIUM_API_KEY" \
  -H "Idempotency-Key: submittal-review-2026-04-08" \
  -F "file=@./Submittal_Review_Template.docx" \
  -F "project_id=8f2e3c1a-..." \
  -F "document_ids=4a1c2b3d-...,9e8f7a6b-..."

field — ext uniquement. Non-DOCX retourne code.
Les fichiers au-dessus de la taille maximale retournent code.
field — UUID de projet optionnel. L'appelant doit avoir accès en vue ou l'endpoint retourne code.
field — UUIDs séparés par des virgules optionnels. Les UUIDs invalides retournent code.

Réponse

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

Le job est créé dans l'état state. Les octets du template sont uploadés dans le stockage objet scopé au tenant et le pipeline de remplissage prend le job en charge.

REST uniquement — pas de MCP

Cette capability est multipart, donc elle n'est pas exposée comme outil MCP. JSON-RPC ne peut pas transporter des pièces jointes binaires. Les agents qui ont besoin d'un template rempli devraient appeler l'endpoint REST directement.

Attachez un Idempotency-Key

Les remplissages de template coûtent 25 tokens et produisent des effets de bord. Passez un header header pour qu'une réponse perdue ne déclenche pas deux fois le même remplissage — voir Idempotence.

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.

templates.get_fill_status

GET/api/v2/templates/fill/{job_id}

Interrogez la progression d'un job de remplissage, l'étape, l'URL de téléchargement présignée et l'état d'erreur.

scope: templates:readcost: 1

Réponse (en cours)

json
{
  "job_id": "c1d2e3f4-...",
  "status": "running",
  "progress": 42,
  "progress_stage": "Filling narrative sections",
  "created_at": "2026-04-08T10:12:00+00:00",
  "started_at": "2026-04-08T10:12:05+00:00",
  "completed_at": null,
  "filled_document_id": null,
  "filled_download_url": null,
  "error_code": null,
  "error_message": null
}

Réponse (terminé)

json
{
  "job_id": "c1d2e3f4-...",
  "status": "completed",
  "progress": 100,
  "progress_stage": "done",
  "created_at": "2026-04-08T10:12:00+00:00",
  "started_at": "2026-04-08T10:12:05+00:00",
  "completed_at": "2026-04-08T10:14:31+00:00",
  "filled_document_id": "9a8b7c6d-...",
  "filled_download_url": "https://alloovium-storage.s3.ap-southeast-2.amazonaws.com/...signed...",
  "error_code": null,
  "error_message": null
}

field est une URL S3 présignée valide 1 heure. Ré-interrogez capability pour la rafraîchir — l'URL est générée fraîche à chaque appel de statut une fois le job terminé.

Réponse (échoué)

json
{
  "job_id": "c1d2e3f4-...",
  "status": "failed",
  "progress": 64,
  "progress_stage": "Filling tables",
  "created_at": "2026-04-08T10:12:00+00:00",
  "started_at": "2026-04-08T10:12:05+00:00",
  "completed_at": "2026-04-08T10:13:47+00:00",
  "filled_document_id": null,
  "filled_download_url": null,
  "error_code": "table_fill_failed",
  "error_message": "Unable to match any source document to the submittal schedule table."
}

États de statut

Statut	Terminal ?	Notes
pending	no	Job created; template uploaded; not yet picked up.
running	no	Pipeline executing. progress + progress_stage update as it runs.
completed	yes	Filled DOCX ready. filled_document_id and filled_download_url are populated.
failed	yes	Runtime error. error_code + error_message explain what went wrong.
cancelled	yes	Cancelled by the user or by a timeout.

Isolement de tenant

Demander un field appartenant à un autre tenant retourne code, pas 403 — nous ne distinguons pas les deux pour que les attaquants ne puissent pas sonder l'espace d'ID.

Pattern d'interrogation

python
import time, httpx

def wait_for_fill(job_id: str, api_key: str, timeout_s: int = 600):
    url = f"https://api.alloovium.com/api/v2/templates/fill/{job_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    deadline = time.monotonic() + timeout_s

    while time.monotonic() < deadline:
        resp = httpx.get(url, headers=headers)
        resp.raise_for_status()
        payload = resp.json()
        status = payload["status"]

        if status == "completed":
            return payload  # filled_download_url is ready
        if status in ("failed", "cancelled"):
            raise RuntimeError(
                f"fill {job_id} ended in {status}: {payload.get('error_message')}"
            )

        time.sleep(3)  # 2-5s polling is ideal

    raise TimeoutError(f"fill {job_id} did not finish in {timeout_s}s")

Téléchargez le DOCX rempli rapidement

field est une URL S3 présignée valide 1 heure. Si vous en avez besoin plus tard, appelez simplement à nouveau capability — il re-signera à chaque requête.

Voir aussi

Workflows — même machine d'état asynchrone, moteur d'exécution différent.
Idempotence — ne déclenchez jamais le même remplissage deux fois.