Documents

Resource Links

A document can be linked to one or more platform resources. Links are lightweight associations - a DocumentLink row that records which resource the document is attached to.

# Supported Resource Types

The resource type is inferred from the ID prefix. No resource_type field is needed in the request body.

# Link a Document to a Resource

        const response = await fetch(`/v1/documents/${docId}/links`, {
  method: "POST",
  headers: { "X-API-KEY": apiKey, "Content-Type": "application/json" },
  body: JSON.stringify({
    resource_id: "ship_abc123",
  }),
});

const { data, message } = await response.json();
// data.id — the new link ID (UUID v7)
// data.resource — { id, type }
// data.restored — true if a soft-deleted link was restored

      

Request body:

Idempotency:

The combination of (document_id, resource_id) has a database-level unique constraint.

Response (new link):

        {
  "data": {
    "id": "019696c6-4b3a-7e1d-b9a2-3f8c1d0e5a72",
    "resource": { "id": "ship_abc123", "type": "shipment" },
    "created_at": 1747094400,
    "document": { "id": "dcmt_01j9abc123" },
    "restored": false
  },
  "message": "Document linked"
}

      

# Remove a Link

Soft-deletes the DocumentLink row. The document itself is not affected.

        await fetch(`/v1/documents/${docId}/links/${linkId}`, {
  method: "DELETE",
  headers: { "X-API-KEY": apiKey },
});
// { data: { id: "019696c6-..." }, message: "Document unlinked" }

      

# List Links

List the active links for a document with optional filters.

        const response = await fetch(
  `/v1/documents/${docId}/links?resource_type=shipment&page=1&limit=25`,
  { headers: { "X-API-KEY": apiKey } }
);
const { data, pagination } = await response.json();

      

Query parameters:

Response:

        {
  "data": [
    {
      "id": "019696c6-4b3a-7e1d-b9a2-3f8c1d0e5a72",
      "resource": { "id": "ship_abc123", "type": "shipment" },
      "created_at": 1747094400
    }
  ],
  "pagination": { "page": 1, "limit": 25, "total": 1 },
  "message": "1 link retrieved"
}

      

# Managing Links via the Update Endpoint

Instead of using the links endpoint, you can manage resource links atomically as part of a document update using the resources field on POST /v1/documents/:id:

        // Add links
{ "resources": { "add": ["ship_abc123", "ful_def456"] } }

// Remove links
{ "resources": { "remove": ["ast_xyz789"] } }

// Replace all links (set)
{ "resources": { "set": ["ship_abc123"] } }

      

The resources field accepts either { add, remove } or { set } - these forms cannot be combined:

The set operation is atomic - it removes links not in the new set and adds new ones in a single transaction.

This approach is useful when you want to update metadata and links in a single request.