API reference

One versioned contract. The same rules as the console.

If a person can do it in the product, an API user with the right scopes can do it over HTTPS. Bytes still travel through Casewelt. Errors still distinguish “badly formed”, “policy said no”, and “that state has already ended”. This page is the map. The pages beside it are the walks.

Authentication Files How it fits

How to call it

HTTPS and JSON. File bytes on the transfer paths. A short code when it fails, so you know whether to fix the body, ask a person, or stop retrying.

	Use this
Host	The organisation host you were issued. Or the API host plus `X-Casewelt-Organisation-Id` when the token already names the organisation.
Version	All organisation paths sit under `/v1`.
Auth	`Authorization: Bearer` from client credentials. A human cookie session cannot mint this token.
JSON	`Content-Type: application/json`, except when you PUT raw file bytes.
Idempotency	`Idempotency-Key` on creates you might retry. Remembered for a day. Same key, different body → `conflict`.
Correlation	`X-Request-Id` if you have one. Casewelt mints one if you do not, and returns it on the problem document as `correlation_id`.
Errors	`application/problem+json` with HTTP status plus a short `code`.
Bytes	Never a storage address. Transfer mode `casewelt_transfer` means Casewelt streams the object.
Recipients	Share, sign, and inbound upload use the public doors. Your Bearer token is not their login.

A first job

Put a pack in a folder, share version 1 with counsel, hear when they open it. Recipients still use the public doors.

Mint, then check

POST /v1/oauth/token, then GET /v1/session/me. Confirm organisation and scopes before you write.

Put the file

Open an upload session, PUT the bytes, complete. You get file_id and version_id. Files →

Create the share

Bind it to that version. Keep the OTP out of band if the mailbox is shared. Sharing →

Listen, then end it

Register a webhook. Deduplicate on event id. Revoke when the fortnight ends. A later open is denied and still arrives. Events →

If create-share is refused, read code. policy_denied — stop and tell a person. A timeout — send the same Idempotency-Key again.

Areas of the API

Who is calling

Mint a token with client credentials. Read /v1/session/me to see the organisation and scopes. Humans cannot exchange their session into this token.

Authentication →

Files and transfer

List workspaces and folders, open an upload session, put bytes, complete, download a named version, create a blank document, search.

Files & transfer →

Sharing and signatures

Create and revoke external shares, list internal shares, send a signature envelope. Organisation download limits apply when you omit them.

Sharing & signatures →

Events out

Register a URL, verify the signature, ignore duplicates, expect retries for seventy-two hours. Administrators can replay a missed delivery.

Events →

The rest of the tenant

People, roles, holds, mail, storage flags, branding, domain, usage — the organisation console, as HTTP.

Organisation API →

Audit and evidence

Search events, pin an investigation, export a sealed package. Not a screenshot of the console.

Audit API →

Opening a customer

A different credential creates organisations. It cannot then read their files.

Channel partners →

Scopes

Scope is checked first. Resource permission is still checked. A files token cannot open a workspace it was never granted.

Scope	What it is for
`organisation`	The whole tenant account: people, roles, billing, storage, mail, domain, security, secrets reveal, and every product path. Not Casewelt’s own operator API.
`files` / `workspaces`	Folders, files, upload, documents, calendar, activity, notifications, file requests.
`shares`	External shares and internal shares.
`signatures`	Signature envelopes.
`office`	Browser editing sessions.
`webhooks`	Event destinations.
`usage`	Read metres: storage, signatures, credits.
`ai`	Assistance. Credits must remain.
`integrations`	Connectors. Reads never return live secrets.
`audit`	Events, investigations, evidence packages.
`reports`	Usage dashboards and exports.

If you omit scopes when minting an API user, Casewelt defaults to files, shares, signatures and office — enough for a product bot, not enough to change billing.

Problem codes you will actually branch on

HTTP	Code	What you should do
403	`deny`	This principal may not do this to this object. Do not retry the same call.
403	`policy_denied`	A rule refused it. The session is still valid. Tell a person, or pick another file.
4xx	`quota_exceeded` / `actor_quota_exceeded`	Stop putting bytes. Ask an administrator for headroom.
401	`invalid_client`	Rotate or re-issue the API user. Do not log the secret.
403	`human_api_forbidden`	A person tried to become automation. Use the portal, or mint a real API user.
409	`conflict` (idempotency)	Same key, different body. Pick a new key or send the original body.

Boundaries

Field-level detail for a live tenant is in the organisation console’s Partner API reference. This map covers the organisation contract. Channel credentials that create tenants are refused here. Bytes move through Casewelt transfer.

Read it against a tenant

Mint a scoped client. Watch a policy refusal.

Bring the system that creates folders, listens for opens, or sends envelopes. We will read the problem document with you.

Discuss an integration