HTTP API

Docsentry exposes a JSON API alongside the web interface. Everything the interface does through an API controller is available programmatically.

Conventions

Versioned routes. Every endpoint lives under /api/v1/. The version is in the path, so a future version can be introduced without breaking existing callers.

Authentication. The API uses the same authentication as the web interface. Requests carry the session cookie established at sign-in.

Request forgery protection. Every POST, PUT, PATCH and DELETE request must send the X-Docsentry-Csrf header. Its value is not a secret; what matters is that a cross-site page cannot add a custom header without a CORS preflight, and Docsentry publishes no CORS policy. A mutating request without the header is refused with 403 and a problem-details body. GET and HEAD need no header.

POST /api/v1/folders HTTP/1.1
Content-Type: application/json
X-Docsentry-Csrf: 1

{ "parentId": null, "name": "Contracts" }

Authorisation. The same access-control model applies. Results are permission-trimmed: a document you cannot access does not appear as a forbidden result, it does not appear at all. See Permission model.

Responses. Request and response bodies are dedicated contracts. Database row models and Identity entities are never exposed.

Errors. Returned as problem details with a defined error taxonomy, not as leaked exception text.

Pagination. Long collections page with an opaque cursor; some bounded reports use page numbers. Page size is bounded by DmsDataAccess:MaxPageSize, 200 by default. Pass a returned cursor back to fetch the next page rather than incrementing an offset.

Cancellation. Every operation honours client disconnection.

Rate limiting. Requests are metered. Exceeding the allowance returns 429 with Retry-After. See Security hardening.

Health

Method	Route	Description
GET	/api/v1/health	Liveness probe. Anonymous, and exempt from rate limiting.

Folders

Method	Route	Description
GET	/api/v1/folders/{id}/children	List child folders and documents.
GET	/api/v1/folders/{id}	Get a folder.
GET	/api/v1/folders/{id}/breadcrumb	Ancestor chain.
GET	/api/v1/folders/{id}/effective-upload-policy	Resolved upload policy for the folder.
POST	/api/v1/folders	Create a folder.
PUT	/api/v1/folders/{id}	Update a folder.
POST	/api/v1/folders/{id}/move	Move a folder and its subtree.
DELETE	/api/v1/folders/{id}	Soft-delete a folder.
POST	/api/v1/folders/{id}/restore	Restore from the recycle bin.
POST	/api/v1/folders/{id}/favorite	Add a favourite.
DELETE	/api/v1/folders/{id}/favorite	Remove a favourite.
GET / PUT / DELETE	/api/v1/folders/{folderId}/upload-policy	Read, set, or clear the folder’s own upload policy.

Documents

Method	Route	Description
GET	/api/v1/documents	List documents.
GET	/api/v1/documents/{id}	Get a document.
GET	/api/v1/documents/{id}/versions	Version history.
GET	/api/v1/documents/{id}/content	Stream content. Refused until the version has cleared scanning.
PUT	/api/v1/documents/{id}	Update a document.
POST	/api/v1/documents/{id}/check-out	Take the edit lock.
POST	/api/v1/documents/{id}/check-in	Release the lock with new content.
POST	/api/v1/documents/{id}/discard-check-out	Release without a new version.
DELETE	/api/v1/documents/{id}	Soft-delete.
POST	/api/v1/documents/{id}/restore	Restore from the recycle bin.
GET	/api/v1/documents/recycle-bin	List deleted documents.
DELETE	/api/v1/documents/{id}/permanent	Permanently delete.

Uploads

Method	Route	Description
POST	/api/v1/uploads	Initiate a resumable upload session.
PUT	/api/v1/uploads/{id}/chunks/{index}	Send one chunk.
POST	/api/v1/uploads/{id}/complete	Assemble and finalise.
POST	/api/v1/uploads/{id}/abort	Abandon the session.

Sessions that are never completed are swept by a background job. See Uploading.

Metadata and classification

Method	Route	Description
GET / PUT	/api/v1/documents/{id}/metadata	Read or set metadata values.
PUT	/api/v1/documents/{id}/content-type	Set the content type.
GET / POST / DELETE	/api/v1/documents/{id}/tags	List, apply, remove tags.
GET / POST / DELETE	/api/v1/documents/{id}/categories	List, apply, remove categories.
POST	/api/v1/documents/{id}/allocate-number	Allocate a document number.

Taxonomy and content types

Method	Route	Description
GET / POST / PUT / DELETE	/api/v1/categories	Manage categories. Deactivate rather than delete.
GET / POST / DELETE	/api/v1/tags	Manage tags. Retire rather than delete.
GET / POST / PUT	/api/v1/content-types	Manage content types, their fields, and option lists.
GET / POST / PUT	/api/v1/numbering-schemes	Manage numbering schemes.

Permissions and sharing

Method	Route	Description
GET	/api/v1/folders/{id}/permissions	Access-control entries on a folder.
PUT / DELETE	/api/v1/folders/{id}/permissions/entries	Set or remove an entry.
PUT	/api/v1/folders/{id}/permissions/inheritance	Break or restore inheritance.
GET	/api/v1/documents/{id}/permissions	Entries on a document.
PUT / DELETE	/api/v1/documents/{id}/permissions/entries	Set or remove an entry.
GET	/api/v1/permissions/effective	Effective permissions for a user on a resource.
GET	/api/v1/permissions/templates	Available permission templates.
GET	/api/v1/permissions/access-levels	The access-level ladder.
GET	/api/v1/subjects/search	Search users, roles, departments, and organisation units.
GET / POST	/api/v1/share-links	List or create share links.
GET / POST	/api/v1/share-links/{id}	Get, revoke, or redeem a link.

Search

Method	Route	Description
GET	/api/v1/search	Quick search.
POST	/api/v1/search/advanced	Structured, faceted search.
GET / POST / PUT / DELETE	/api/v1/saved-searches	Manage saved searches; run one by id.

Previews and scanning

Method	Route	Description
GET	/api/v1/documents/{id}/preview	Preview image. Not cached, because it depends on the caller.
GET	/api/v1/documents/{id}/thumbnail	Thumbnail. Cached.
GET	/api/v1/documents/{id}/preview/status	Generation status.
GET	/api/v1/documents/{id}/scan-status	Antivirus scan status.
POST	/api/v1/documents/{id}/rescan	Re-queue a scan. Administrator only.

Workflows

Method	Route	Description
GET	/api/v1/workflows/definitions	Active definitions.
GET	/api/v1/workflows/inbox	Your assigned tasks, paged.
GET	/api/v1/workflows/tasks/{id}	One task.
GET	/api/v1/workflows/instances/{id}	One instance.
GET	/api/v1/workflows/instances/{id}/history	Append-only action history.
POST	/api/v1/workflows/start	Start a workflow on a document.
POST	/api/v1/workflows/act	Take an action on a task.
POST	/api/v1/workflows/delegate	Delegate a task.
POST	/api/v1/workflows/escalate	Escalate a task.
POST	/api/v1/workflows/assign	Reassign a step.
GET / POST / PUT	/api/v1/workflow-definitions	Author definitions, steps, and transitions.

Collaboration and notifications

Method	Route	Description
GET / POST	/api/v1/documents/{id}/comments	List or add comments.
PUT / DELETE	/api/v1/comments/{id}	Edit or delete a comment.
GET	/api/v1/documents/{id}/activity	Activity timeline.
GET / POST / DELETE	/api/v1/favorites	Manage favourites.
GET / POST / DELETE	/api/v1/watches	Manage resource watches.
GET	/api/v1/notifications	Your notifications.
GET	/api/v1/notifications/unread-count	Unread badge count.
POST	/api/v1/notifications/read	Mark read, individually or all.
GET / POST	/api/v1/reminders	Manage reminders.
GET / PUT	/api/v1/email-preferences	Your notification email preferences.

Signatures

Method	Route	Description
GET	/api/v1/signatures	Signature records on a document.
GET	/api/v1/signatures/pending	Requests awaiting you.
POST	/api/v1/signatures/request	Request a signature.
POST	/api/v1/signatures/sign	Apply a signature.
POST	/api/v1/signatures/decline	Decline a request.
POST	/api/v1/signatures/revoke	Revoke a request.
GET	/api/v1/documents/{id}/versions/{versionId}/signing-base	The signing base, and per-page rasters.
GET	/api/v1/documents/{id}/versions/{versionId}/signed-rendition	Composed rendition. Served with an ETag.
GET	/api/v1/documents/{id}/versions/{versionId}/signatures/verify	Verify. Tamper-evidence, not non-repudiation.
GET / PUT / DELETE	/api/v1/folders/{id}/signing-capability	Folder signing capability.
GET / PUT / DELETE	/api/v1/documents/{id}/signing-requirement	A document’s signing requirement definition.
GET / PUT / DELETE	/api/v1/folders/{id}/signing-requirement	A folder’s signing requirement definition.
GET / POST	/api/v1/documents/{id}/signing-requirement/instance	The active requirement for the current version, or activate it.
POST	/api/v1/signing-requirement-instances/{id}/cancel	Cancel an active requirement.

Governance

Method	Route	Description
GET / PUT	/api/v1/governance/watermark	Watermark settings.
GET / PUT	/api/v1/governance/settings	System settings.
GET	/api/v1/governance/retention	Retention configuration.
GET / PUT	/api/v1/admin/retention-settings	Update retention.

Reports

Method	Route	Parameters
GET	/api/v1/reports/audit	from, to, page, pageSize
GET	/api/v1/reports/workflow-completion	cursor, pageSize
GET	/api/v1/reports/storage-usage	cursor, pageSize
GET	/api/v1/reports/security-health	cursor, pageSize
GET	/api/v1/reports/inactive-documents	olderThan, page, pageSize
GET	/api/v1/reports/large-files	minBytes, page, pageSize
GET	/api/v1/reports/duplicate-files	cursor, pageSize
GET	/api/v1/reports/signing-requirements	page, pageSize
GET	/api/v1/reports/{report}/export.csv	Same parameters as the report

Dashboards and administration

Method	Route	Description
GET	/api/v1/dashboard/me	Your dashboard model.
GET	/api/v1/dashboard/admin	Administrative dashboard model.
GET / POST / PUT / DELETE	/api/v1/admin/roles	Manage roles and membership.
GET / POST / PUT / DELETE	/api/v1/admin/departments	Manage departments.
GET / POST / PUT / DELETE	/api/v1/admin/organization-units	Manage organisation units and membership.
GET / PUT	/api/v1/admin/upload-allowlist	The global upload allowlist.
GET / PUT / POST	/api/v1/admin/email-settings	Effective email state, the administrator switch and categories, and a test send.
GET / PUT	/api/v1/email-preferences	Your own email notification preferences.

Related

• Permission model - what trims your results.
• Configuration keys - page-size and rate-limit bounds.