Documents
The Documents API manages files inside iBinder binders. Every file is represented by a document that owns one or more document versions — the version holds the actual file content. This page walks through the most common flows with prose, then shows the full reference for each endpoint.
Authentication
All endpoints require an OAuth 2.0 access token and the x-ibinder-tenantid header. See the Authentication guide.
Browsing a binder's contents
iBinder organises documents into drives (top-level storage areas within a binder) and folders (nested containers). Most integrations start by enumerating the folders in a binder, then drilling into a folder to list its documents.
The three endpoints below mirror each other — they each take a domain (typically binders) plus the binder id, optionally a folder id, and return the next level of the hierarchy.
List folders in drive
List the top-level folders/tabs of a drive. A drive is identified by a
domain (e.g. binders) and an id of an object in that domain
(typically a binder id, a 9-character NanoId).
Authorizations
OAuth 2.0 Client Credentials flow. Obtain a token from the iBinder Identity
Provider, then send it as Authorization: Bearer <token> on every request.
The token endpoint expects grant_type=client_credentials, your client_id,
your client_secret, and scope=ibinder_public.
clientCredentials Flow
"https://signin.ibinder.com/connect/token""ibinder_public"
Parameters
Header Parameters
Path Parameters
Drive domain. Most commonly binders.
Object identifier within the domain. For binders this is a 9-character NanoId.
Responses
The request has succeeded.
List folders in folder
List the sub-folders of a folder within a drive.
Authorizations
OAuth 2.0 Client Credentials flow. Obtain a token from the iBinder Identity
Provider, then send it as Authorization: Bearer <token> on every request.
The token endpoint expects grant_type=client_credentials, your client_id,
your client_secret, and scope=ibinder_public.
clientCredentials Flow
"https://signin.ibinder.com/connect/token""ibinder_public"
Parameters
Header Parameters
Path Parameters
Identifier of the parent folder (typically a GUID).
Responses
The request has succeeded.
List documents in folder
List documents in a folder. The folder is identified by a drive
(domain + id) and a folderId (typically a TabId GUID within a binder).
Authorizations
OAuth 2.0 Client Credentials flow. Obtain a token from the iBinder Identity
Provider, then send it as Authorization: Bearer <token> on every request.
The token endpoint expects grant_type=client_credentials, your client_id,
your client_secret, and scope=ibinder_public.
clientCredentials Flow
"https://signin.ibinder.com/connect/token""ibinder_public"
Parameters
Header Parameters
Path Parameters
Responses
The request has succeeded.
Searching documents
When you need to find documents by metadata rather than by browsing a tree, use the search endpoint. It supports multi-key metadata filters, multi-field sorting, free-text search, and server-side pagination — see the Pagination & filtering guide for the full pattern.
Search/filter documents
Search and filter documents across the tenant. Combines metadata filters,
sorting, and free-text search; supports server-side pagination via the
pageSize, pageNumber, and searchTerm query parameters.
Common patterns:
- Filter to a binder:
MetadataFilters[].metadataElementId = GLOBAL_BinderIdwith the binder id asvalueId. - Filter to a tab/folder:
GLOBAL_TabIdwith the tab id asvalueId. - Sort by category:
SortBy[].metadataElementId = GLOBAL_Category.
Authorizations
OAuth 2.0 Client Credentials flow. Obtain a token from the iBinder Identity
Provider, then send it as Authorization: Bearer <token> on every request.
The token endpoint expects grant_type=client_credentials, your client_id,
your client_secret, and scope=ibinder_public.
clientCredentials Flow
"https://signin.ibinder.com/connect/token""ibinder_public"
Parameters
Header Parameters
Query Parameters
Number of items per page. Defaults to a server-defined value.
"int32"1-based page number.
"int32"Free-text search term applied to document names.
Request Body
Responses
The request has succeeded.
Reading a document and its versions
Given a document id (returned by browsing or searching), you can fetch the document, enumerate its versions, and fetch a specific version's metadata.
Get document
Fetch a document by its identifier. The response describes the document's metadata and latest version pointer.
Authorizations
OAuth 2.0 Client Credentials flow. Obtain a token from the iBinder Identity
Provider, then send it as Authorization: Bearer <token> on every request.
The token endpoint expects grant_type=client_credentials, your client_id,
your client_secret, and scope=ibinder_public.
clientCredentials Flow
"https://signin.ibinder.com/connect/token""ibinder_public"
Parameters
Header Parameters
Path Parameters
Document identifier (GUID).
Responses
The request has succeeded.
List document versions
List all versions of a document, ordered by creation date.
Authorizations
OAuth 2.0 Client Credentials flow. Obtain a token from the iBinder Identity
Provider, then send it as Authorization: Bearer <token> on every request.
The token endpoint expects grant_type=client_credentials, your client_id,
your client_secret, and scope=ibinder_public.
clientCredentials Flow
"https://signin.ibinder.com/connect/token""ibinder_public"
Parameters
Header Parameters
Path Parameters
Responses
The request has succeeded.
Get document version
Fetch a specific document version.
Authorizations
OAuth 2.0 Client Credentials flow. Obtain a token from the iBinder Identity
Provider, then send it as Authorization: Bearer <token> on every request.
The token endpoint expects grant_type=client_credentials, your client_id,
your client_secret, and scope=ibinder_public.
clientCredentials Flow
"https://signin.ibinder.com/connect/token""ibinder_public"
Parameters
Header Parameters
Path Parameters
Document version identifier (GUID).
Responses
The request has succeeded.
Downloading file content
Document versions return only metadata — the binary file content sits in storage. To get a usable download URL, call the dedicated endpoint. The returned URL is short-lived and points directly at storage; do not add an Authorization header when fetching it.
Get document version download link
Get a short-lived presigned download URL for a document version's binary
content. The returned URL points directly at storage; clients should not
add the Authorization header when fetching it.
Authorizations
OAuth 2.0 Client Credentials flow. Obtain a token from the iBinder Identity
Provider, then send it as Authorization: Bearer <token> on every request.
The token endpoint expects grant_type=client_credentials, your client_id,
your client_secret, and scope=ibinder_public.
clientCredentials Flow
"https://signin.ibinder.com/connect/token""ibinder_public"
Parameters
Header Parameters
Path Parameters
Responses
The request has succeeded.
Uploading a new document version
Uploads are a three-step flow designed to avoid streaming binary content through the iBinder API.
- Get a presigned URL. Call
GET /documents/uploads/personalstorage/presigneduploadto receive apresignedUrland anuploadId. - Upload the file directly to storage. Issue a
PUTto thepresignedUrlwith the file bytes as the body. For Azure Blob Storage targets, includex-ms-blob-type: BlockBlob. This call does not go through the iBinder API and does not require your access token. The presigned URL is one-shot — eachuploadIdcan be PUT to exactly once. - Commit the upload. Call
POST /documents/drives/{domain}/{id}/{folderId}/uploadwith theuploadId, the desired filename, a version label, and any additional metadata. The server materialises the upload into a new document version in the target folder.
Idempotency
The commit call is keyed by uploadId — committing the same uploadId twice will not create duplicate document versions.
Full upload example
const API = 'https://api.ibinder.com/api'
const headers = {
Authorization: `Bearer ${accessToken}`,
'x-ibinder-tenantid': orgId,
}
// 1. Get a presigned URL
const { presignedUrl, uploadId } = await fetch(
`${API}/documents/uploads/personalstorage/presignedupload`,
{ headers },
).then(r => r.json())
// 2. PUT the file bytes directly to storage — no Authorization header here
await fetch(presignedUrl, {
method: 'PUT',
headers: { 'x-ms-blob-type': 'BlockBlob' },
body: fileBytes,
})
// 3. Commit the upload into the target folder
const commit = await fetch(
`${API}/documents/drives/binders/${binderId}/${folderId}/upload`,
{
method: 'POST',
headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({
uploadId,
fileName: 'contract.pdf',
versionLabel: '1.0',
metadata: [
// optional: { metadataElementId: '...', valueId: '...' }
],
}),
},
).then(r => r.json())
console.log('Created version', commit.id)API=https://api.ibinder.com/api
H_AUTH="Authorization: Bearer $TOKEN"
H_TEN="x-ibinder-tenantid: $IBINDER_ORG_ID"
# 1. Presigned URL
RESP=$(curl -s "$API/documents/uploads/personalstorage/presignedupload" \
-H "$H_AUTH" -H "$H_TEN")
URL=$(echo "$RESP" | jq -r .presignedUrl)
UPLOAD_ID=$(echo "$RESP" | jq -r .uploadId)
# 2. PUT the file straight to storage (no bearer)
curl -s -X PUT "$URL" \
-H "x-ms-blob-type: BlockBlob" \
--data-binary @contract.pdf
# 3. Commit
curl -s -X POST "$API/documents/drives/binders/$BINDER_ID/$FOLDER_ID/upload" \
-H "$H_AUTH" -H "$H_TEN" -H "Content-Type: application/json" \
-d "{\"uploadId\":\"$UPLOAD_ID\",\"fileName\":\"contract.pdf\",\"versionLabel\":\"1.0\"}"Get new presigned URL for upload
Step 1 of the three-step upload flow: request a one-shot presigned URL that
accepts a PUT of the file contents. The returned uploadId is then passed
to the commit endpoint after the PUT completes.
Authorizations
OAuth 2.0 Client Credentials flow. Obtain a token from the iBinder Identity
Provider, then send it as Authorization: Bearer <token> on every request.
The token endpoint expects grant_type=client_credentials, your client_id,
your client_secret, and scope=ibinder_public.
clientCredentials Flow
"https://signin.ibinder.com/connect/token""ibinder_public"
Responses
The request has succeeded.
Commit uploaded file as document version
Step 3 of the three-step upload flow: after PUTting the file to the
presigned URL, commit the upload into a new document version in the target
folder. Metadata supplied here is attached to the resulting version.
Authorizations
OAuth 2.0 Client Credentials flow. Obtain a token from the iBinder Identity
Provider, then send it as Authorization: Bearer <token> on every request.
The token endpoint expects grant_type=client_credentials, your client_id,
your client_secret, and scope=ibinder_public.
clientCredentials Flow
"https://signin.ibinder.com/connect/token""ibinder_public"
Parameters
Header Parameters
Path Parameters
Request Body
Responses
The request has succeeded.