Documents

Managing Documents

# Update a Document

Update mutable fields on an existing document. The schema is strict — any field not in the allowed set returns a 400 validation error.

Mutable fields:

Immutable fields — these cannot be changed after creation: filename, visibility.

        await fetch(`/v1/documents/${docId}`, {
  method: "POST",
  headers: { "X-API-KEY": apiKey, "Content-Type": "application/json" },
  body: JSON.stringify({
    display_name: "Invoice April 2026 (Revised)",
    metadata: { po_number: "PO-12345", revised: true },
  }),
});

      

# Async Upload Verification

The update endpoint also triggers upload verification for requested documents. If upload_status is "requested", the API performs a GCS HEAD check on every update call - including calls with an empty body {}.

This means you can call POST /v1/documents/:id with no fields to purely trigger verification:

        // Poll after the GCS PUT completes
await fetch(`/v1/documents/${docId}`, {
  method: "POST",
  headers: { "X-API-KEY": apiKey, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});

      

See Upload Modes for the full verification state machine.

# Updating Resource Links

Pass a resources object to add, remove, or replace resource links without using the links endpoint:

        // Add a link
{ "resources": { "add": ["ship_abc123"] } }

// Remove a link
{ "resources": { "remove": ["ast_xyz789"] } }

// Replace all links
{ "resources": { "set": ["ship_abc123", "ful_def456"] } }

      

The set operation atomically removes any links not in the new set and adds any new ones. Soft-deleted links for the same resource are restored rather than re-inserted.

# Delete a Document

Soft-deletes the document and all its active links. The document will no longer appear in list or retrieve responses. The GCS object is not deleted from storage.

        const response = await fetch(`/v1/documents/${docId}`, {
  method: "DELETE",
  headers: { "X-API-KEY": apiKey },
});

const { data, message } = await response.json();
// message === "Document deleted"
// data.id === docId

      

Response:

        {
  "data": { "id": "dcmt_01j9abc123" },
  "message": "Document deleted"
}

      

Deleted documents return 404 on subsequent retrieve attempts.