Annotation Status Workflow

When a document is uploaded, the annotation progresses through various states. Understanding this workflow is crucial for agents and applications using the MCP server.

Annotation States

  1. importing - Initial state after upload. Document is being processed.

  2. to_review - Extraction complete, ready for user validation.

  3. reviewing - A user is currently reviewing the annotation.

  4. confirmed - The annotation has been validated and confirmed.

  5. exporting - The annotation is being exported.

  6. exported - Final state for successfully processed documents.

Other possible states include: created, failed_import, split, in_workflow, rejected, failed_export, postponed, deleted, purged.

Important Considerations

Important: After uploading documents, agents should wait for annotations to transition from importing to to_review (or confirmed/exported) before considering them fully processed. Use get(entity="annotation", entity_id=...) to poll individual annotations or search(query={"entity": "annotation", "queue_id": ...}) to check the status of multiple documents in bulk.

Example Workflows

Single Document Upload

  1. Upload a document:

Use upload_document with:
- file_path: "/path/to/invoice.pdf"
- queue_id: "12345"
Response: { task_id: "67890", ... }

  1. Wait for processing and check status:

Use search with:
- query: {"entity": "annotation", "queue_id": 12345}
Find the annotation in the results

Use get with:
- entity: "annotation"
- entity_id: annotation_id_from_search
Check status field - wait until it's "to_review", "confirmed", or "exported"

Bulk Document Upload

For agents uploading multiple documents:

  1. Upload all documents in bulk:

For each file:
  Use upload_document with file_path and queue_id
  Store returned task_ids

  1. Check status of all annotations:

Use search with:
- query: {"entity": "annotation", "queue_id": 12345, "status": "to_review", "ordering": ["-created_at"]}

This returns all annotations in the queue, allowing you to verify
which documents have finished processing.

Error Handling

The server provides detailed error messages for common issues:

  • Missing API token

  • File not found

  • Upload failures

  • API errors

All errors are returned in the tool response with appropriate error messages and stack traces for debugging.