Sync library documents and folders

#Authentication

Use Authorization: Bearer sk_your_api_key and Content-Type: application/json. Secret API keys operate within their workspace. Public write keys and channel keys cannot access these endpoints.

#Endpoints

Replace {resource} with documents or folders.

Method	Path	Behavior
POST	/v1/library/{resource}	Create a new item. Returns 201.
GET	/v1/library/{resource}/{id}	Read by Bigmind ID.
PATCH	/v1/library/{resource}/{id}	Update by Bigmind ID. Returns 404 if missing.
GET	/v1/library/{resource}/external/{externalId}	Read by external ID.
PUT	/v1/library/{resource}/external/{externalId}	Create or update by external ID. Returns 201 when created, 200 when updated. Omitted fields remain unchanged.
DELETE	/v1/library/{resource}/{id}	Delete by Bigmind ID.
DELETE	/v1/library/{resource}/external/{externalId}	Delete by external ID.

URL-encode the external ID as one path segment, including slashes. External IDs are case-sensitive and scoped to the workspace and resource type; a folder and document can use the same external ID. Use a source prefix if syncing multiple systems.

#Request fields

Field	Behavior
title	Nonempty string. Required when creating; optional when updating.
content	HTML string, documents only. Replaces the complete content. An empty string clears it; omission preserves it.
external_id	Optional string on POST or PATCH by Bigmind ID. Null clears the mapping. On external-ID PUT, the path supplies this value; do not repeat it in the body.
parent_external_id	External ID of an existing folder in this workspace. Use this to define the hierarchy entirely with external IDs.
parent_id	Bigmind ID of an existing folder, or null to move to the root. Mutually exclusive with parent_external_id.
access_type	open or restricted. Defaults to open on creation; preserved when omitted on update.
metadata	JSON object. Replaces the metadata object when supplied; omitted metadata is preserved.

External IDs may contain up to 1024 characters. Unknown fields are rejected. These endpoints do not change an item's type, purpose, template, sources, or relations. Updates by Bigmind ID preserve those existing fields.

#Sync a hierarchy using only external IDs

Create parent folders before syncing their children. The parent reference must already resolve to a folder; missing parents are not created implicitly.

PUT /v1/library/folders/external/source-root
{"title":"Knowledge base"}

PUT /v1/library/folders/external/source-product
{"title":"Product guides","parent_external_id":"source-root"}

PUT /v1/library/documents/external/source-guide
{"title":"Getting started","content":"<h1>Getting started</h1><p>Guide content</p>","parent_external_id":"source-product"}

PUT /v1/library/folders/external/source-root
{"title":"Knowledge base"}

PUT /v1/library/folders/external/source-product
{"title":"Product guides","parent_external_id":"source-root"}

PUT /v1/library/documents/external/source-guide
{"title":"Getting started","content":"<h1>Getting started</h1><p>Guide content</p>","parent_external_id":"source-product"}

Repeat these PUT requests to sync changes without creating duplicates. To change only the content:

PUT /v1/library/documents/external/source-guide
{"content":"<p>Updated guide</p>"}

PUT /v1/library/documents/external/source-guide
{"content":"<p>Updated guide</p>"}

To move a folder and its existing subtree under another folder, update its parent_external_id. Omit both parent fields to preserve the location, or send parent_id: null to move to the library root.

#Sync using Bigmind IDs

PATCH /v1/library/documents/BIGMIND_DOCUMENT_ID
{"content":"<p>Updated guide</p>","external_id":"source-guide"}

PATCH /v1/library/folders/BIGMIND_FOLDER_ID
{"title":"Renamed guides","parent_external_id":"source-root"}

PATCH /v1/library/documents/BIGMIND_DOCUMENT_ID
{"content":"<p>Updated guide</p>","external_id":"source-guide"}

PATCH /v1/library/folders/BIGMIND_FOLDER_ID
{"title":"Renamed guides","parent_external_id":"source-root"}

#Delete synced items

DELETE /v1/library/documents/external/source-guide
DELETE /v1/library/documents/BIGMIND_DOCUMENT_ID
DELETE /v1/library/folders/external/source-product

DELETE /v1/library/documents/external/source-guide
DELETE /v1/library/documents/BIGMIND_DOCUMENT_ID
DELETE /v1/library/folders/external/source-product

Delete requests need no body. Success returns HTTP 200 with {"success":true,"data":{"id":"...","deletedCount":1}}. A missing or already deleted item returns 404. Folder deletion requires an empty folder; otherwise it returns 409. Delete children first, then their parent folders. Deletion is permanent and uses the normal library cleanup for associations and search indexing.

#Responses and errors

Successful responses have the shape {"success":true,"data":{"id":"...","external_id":"...","title":"...","content":"...","parent_id":"..."}}, with the library item's other fields included. Store the returned Bigmind ID if useful. Each request handles one item; there is no batch transaction.

Errors have the shape {"success":false,"error":"..."}. Status 400 means invalid input or a folder cycle; 401 means missing or invalid authentication; 403 rejects public write keys; 404 means the item or parent was not found in the workspace; 409 means an external ID conflict, ambiguity, or a nonempty folder; 500 means an internal failure. Existing purpose-specific documents can share an external ID, so ambiguous lookups return 409; use a Bigmind ID to update one explicitly.

Use external IDs to retry document and folder sync requests without creating duplicate items. Search results update in the background after you change or delete a document. Sync does not delete items omitted from the source.