HTTP operation reference#

This reference is generated from the v1 OpenAPI contract. Paths starting /api/v1/ are absolute; normal requests require Authorization: Bearer and X-Org-ID unless the operation specifies another authority. Start with API conventions, sharing, and IAM OBO.

All operations below have revision 1.0.0. Public links expose read/download only. Test selection always uses X-Briefcase-App-Secret in addition to the stated actor authority.

Read the public IAM application ID before login#

GET /iam · readIamInfo

No member token or organization is required. An optional X-Briefcase-App-Secret selects the paired test application's identity. Application secrets and environment keys are never returned.

Authority: anonymous.

Verify the current Carbon or Silicon session with IAM#

GET /auth/status · readLoginStatus

No organization selection is required. Missing, invalid, expired, or revoked member tokens return authenticated false. Active tokens return their identity and currently granted organizations; an empty grant list does not make an active session unauthenticated. IAM outages, malformed upstream responses, and invalid test-plane credentials remain errors.

Authority: anonymous or bearerAuth or bearerAuth + testingEnvironmentKey.

Report the API version and per-operation contract revisions#

GET /version · readApiVersion

The compatibility document a client reads before its first real call. It names the API majors this build serves, the one selected for the caller, and every operation with the revision of its request and response shape.

A client advertises the majors it supports, newest first, in Briefcase-Supported-API-Versions. The server answers with the newest both sides support in Briefcase-API-Version, and 406 when there is none. Vary names the request header, so a cache never serves one client's selection to another.

An operation's version changes whenever its request or response shape changes observably; adding an operation leaves the others alone. A client that verifies its own operations against this list fails at startup rather than at the first call that no longer means what it did.

Also served unversioned at /api/version, so a client can negotiate before it knows which base path to use.

Authority: anonymous.

Exchange an IAM short-lived token for a Briefcase Application session#

POST /auth/slt · exchangeShortLivedToken

Accepts only the single-use SLT obtained from IAM's hosted Application login. Briefcase supplies its own Application credential. When X-Briefcase-App-Secret is present, Briefcase uses only the mapped IAM testing-environment key and test-only Application credential. Preserve the same Idempotency-Key when recovering an uncertain result.

Authority: anonymous.

Request: application/json (required).

Rotate an IAM Application refresh token#

POST /auth/refresh · refreshApplicationSession

A successful refresh consumes the presented token and returns its replacement. Serialize refreshes per token family. Retry an uncertain result only with the exact same token, Idempotency-Key, and testing environment selection; rejected refreshes are terminal.

Authority: anonymous.

Request: application/json (required).

List Briefcase testing environments owned by an organization#

GET /organizations/{org_id}/testing-environments · listTestingEnvironments

This lifecycle route always authenticates in production. The path organization must equal X-Org-ID. Active environments are returned by default; status=deleted or status=all changes that selection.

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Create an empty Briefcase testing environment#

POST /organizations/{org_id}/testing-environments · createTestingEnvironment

Provisions an IAM application testing environment through the official SDK and creates its empty Briefcase data plane. The IAM root credential and application secret are encrypted at rest. The returned key is the IAM test application secret (ask_ followed by 43 URL-safe characters), which selects this plane in X-Briefcase-App-Secret. At most ten environments may be active and each has a 2 GiB storage ceiling. Completed retries recover the original encrypted response.

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Request: application/json (required).

Read one testing environment without revealing credentials#

GET /organizations/{org_id}/testing-environments/{environment_id} · getTestingEnvironment

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Rename or re-describe an active testing environment#

PATCH /organizations/{org_id}/testing-environments/{environment_id} · updateTestingEnvironment

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Request: application/merge-patch+json (required).

Request: application/json (required).

Retire an environment with a two-day recovery window#

DELETE /organizations/{org_id}/testing-environments/{environment_id} · deleteTestingEnvironment

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Retrieve the selected IAM test application secret#

GET /organizations/{org_id}/testing-environments/{environment_id}/key · getTestingEnvironmentKey

Restricted to the creator or a current organization admin/owner.

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Replace every credential in the paired IAM testing plane#

POST /organizations/{org_id}/testing-environments/{environment_id}/iam-pairings · replaceTestingEnvironmentIamPairing

Restricted to the creator or an organization administrator. Verify the complete replacement IAM pairing live. Replacing the app secret immediately replaces the Briefcase selector and advances the control/key generation. Existing initialized data cannot be rebound to a different IAM environment identity; create a new environment for that. Lifecycle changes wait for accepted work through the environment fence.

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Request: application/json (required).

Erase an environment's isolated data while retaining its key#

POST /organizations/{org_id}/testing-environments/{environment_id}/cleanings · cleanTestingEnvironment

Atomically erases Briefcase content, versions, permissions, logs, notifications, idempotency state, storage settings, and consumption. Exact provider deletion and multipart-abort descriptors are durably queued before source metadata is removed, then retried by the worker. The paired IAM directory projection is retained so existing test identities can use the empty environment immediately; deterministic roots are rebuilt on their next request.

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Restore a retired environment before its purge deadline#

POST /organizations/{org_id}/testing-environments/{environment_id}/restorations · restoreTestingEnvironment

Restore before the two-day purge deadline, provided the paired IAM environment and application credential remain valid. Returns the current IAM app secret and advances the control generation.

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Describe the environment selected by its IAM app secret#

GET /testing-environment · describeCurrentTestingEnvironment

Authority: testingEnvironmentKey.

Erase isolated Briefcase data using its test app secret#

POST /testing-environment/cleanings · cleanCurrentTestingEnvironment

Uses only the selected environment root as authority and performs the same atomic Briefcase-state erasure as the production control-plane cleaning route while retaining the paired IAM identity projection. Provider deletion is durably queued and retried after logical erasure.

Authority: testingEnvironmentKey.

List folder contents, or filter everything the caller can reach#

GET /entries · listEntries

Returns the hundred most recently changed visible entries per page, newest first. Without filter, the listing browses one level: the organization roots, or the contents of parent_id/path. With filter and no parent, it searches every entry the caller may reach, which is how a location: predicate selects a subtree.

The filter language combines freely. Terms are ANDed; or introduces an alternative; not or a leading - negates; parentheses group. Supported keys:

last:N / first:N take N entries chronologically (1-100, single page); sort:newest / sort:oldest order the result, newest first by default; between:DD-MM-YYYY=DD-MM-YYYY bounds the last change with both days inclusive; after:DD-MM-YYYY and before:DD-MM-YYYY bound one side; from:@{carbon:id} matches the creator; to:@{silicon:id} matches an explicit share; for:@{id} matches what that member can reach; contains:'term' matches names and extracted content, with * as a wildcard; has:'term' matches extracted content only; name:'term' matches names only; location:'private/cos:tos' matches a path prefix; is: takes file, folder, a renderer (image, video, document, spreadsheet, presentation, audio, archive, code, unsupported), or an extension such as md; permissions: takes read, write, update, delete, or manage_permissions and matches the caller's effective access. A bare word is shorthand for contains:.

Filtering only ever returns entries the caller can already see.

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

createFolder#

POST /entries · createFolder

Without a parent, creates a user folder at the organization base with the required root_type access boundary (and IAM tag for type tag). The new folder is a sibling of the reserved containers, not redirected into one. With parent_id or parent_path, creates inside that folder and inherits its boundary. Existing folders are not relocated. Sibling name collisions return 409 without exposing hidden entry metadata.

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Request: application/json (required).

getEntry#

GET /entries/{entry_id} · getEntry

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

updateEntry#

PATCH /entries/{entry_id} · updateEntry

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Request: application/json (required).

moveEntryToBin#

DELETE /entries/{entry_id} · moveEntryToBin

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Stream current file bytes for sandboxed in-place rendering#

GET /entries/{entry_id}/content · readEntryContent

Briefcase relays the bytes itself, so the response is always bound to a current IAM identity and is never cacheable. Responses are sandboxed by Content-Security-Policy and served with X-Content-Type-Options: nosniff. Byte ranges are supported for media playback.

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Download current file bytes as an attachment#

GET /entries/{entry_id}/download · downloadEntry

Streams file bytes or a tar.zst folder archive. Folder archives include only entries the caller may read. No whole archive is buffered. Range requests apply to files only.

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Upload a file of any supported size#

POST /uploads · uploadFile

One request carries the whole file. Briefcase stages the bytes, then decides internally whether they fit a single provider request or need a multipart transfer, so a client never drives parts. Files up to 5 TiB are accepted; operators size the upload deadline and temporary disk for the sizes they expect.

The destination folder is named either by parent_id or by path, never both. A path is resolved from the organization base, so private/cos:tos/reports addresses the same folder its permanent URL shows.

Uploading a name that an active file already carries is how a file is updated: the bytes become that file's next version, the response is that same entry, and its history keeps the previous complete version history. Creating a file needs write on the folder; replacing one needs update on the file. A folder with the same name is a conflict.

Two organization limits apply: 100 GiB of uploads per UTC day, and 1 PiB of storage. The daily figure counts uploaded bytes and returns at midnight UTC; the storage figure counts what is currently kept, so deleting content returns capacity once the bytes are gone. Either limit may be configured per organization. An upload that does not fit is refused before its bytes are stored, and GET /usage reports both.

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Request: multipart/form-data (required).

listPermissions#

GET /entries/{entry_id}/permissions · listPermissions

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

grantPermission#

POST /entries/{entry_id}/permissions · grantPermission

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Request: application/json (required).

revokePermission#

DELETE /entries/{entry_id}/permissions/{grant_id} · revokePermission

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Report what the caller may do on named files and folders#

POST /permissions/effective · inspectEffectivePermissions

Names up to 100 targets by identifier, path, or both. A target that does not exist and one the caller cannot read are both reported as unresolved, so the answer never confirms a hidden entry.

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Request: application/json (required).

searchFiles#

GET /search · searchFiles

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Read the central notification inbox#

GET /notifications · listNotifications

Returns the twenty newest notifications for the authenticated Carbon or Silicon together with the unread count used for the badge.

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Mark the entire notification inbox read#

POST /notifications/read · readNotifications

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Read the retained action history of an entry#

GET /entries/{entry_id}/activity · listEntryActivity

Returns up to the last hundred recorded actions on the entry — who created, read, updated, downloaded, deleted, or restored it, and when.

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Create a file for a member on behalf of another application#

POST /obo/files · createFileOnBehalfOfMember

The compatible one-shot delegated file upload. The request body is the raw file bytes, and everything else — the destination folder path, the file name, and the media type — travels as metadata bound into the IAM OBO proof, so an application cannot redirect a proof it legitimately obtained to another destination.

Register the endpoint in IAM as briefcase.files.create at the path /api/v1/obo/files with metadata keys path (empty selects the application's own folder under apps/{app_id}/private/{actor}), name, and content_type. Exchange the proof over the SHA-256 digest of the exact bytes, then send those bytes here. Verification consumes the proof exactly once and is never retried.

The represented member's own permissions still apply: the file is only created where that member may add content, and a name that an active file already carries publishes that file's next version. Any supported size is accepted; Briefcase picks the storage route internally, and the organization's daily and total upload allowances apply as usual.

Authority: oboAccess + appId or oboAccess + appId + testingEnvironmentKey.

Request: application/octet-stream (required).

Reserve private upload storage with current member authority#

POST /obo/uploads/reserve · reserveDelegatedUpload

Register briefcase.uploads.reserve at /api/v1/obo/uploads/reserve. The exact destination, logical operation UUID, size and lowercase SHA-256 are immutable. A fresh proof binds POST and the exact JSON digest with empty metadata. A repeated reservation with unchanged intent can return its current state; a capability is issued only when a transfer can start. Store the non-secret operation UUID and manifest for reconciliation, never a parent token or proof. Capabilities do not authorize publication.

Authority: oboAccess + appId or oboAccess + appId + testingEnvironmentKey.

Request: application/json (required).

Publish previously staged bytes with fresh member authority#

POST /obo/uploads/commit · commitDelegatedUpload

Register briefcase.uploads.commit at /api/v1/obo/uploads/commit. Mint a new proof after transfer, binding this small JSON body and empty metadata. Current IAM identity, membership, originating application, test generation, destination permission and quota are rechecked before atomic publication. The capability cannot commit. A response lost after publication is reconciled by the same logical operation UUID without creating another file version.

Authority: oboAccess + appId or oboAccess + appId + testingEnvironmentKey.

Request: application/json (required).

Reconcile one logical upload with a fresh IAM proof#

POST /obo/uploads/status · getDelegatedUploadStatus

Register briefcase.uploads.status at /api/v1/obo/uploads/status. Use a fresh proof for the exact JSON body and empty metadata after an uncertain response. This endpoint returns only the represented member and originating application's operation in the selected plane. It does not return a staging capability or read file bytes. A staged result can be committed with another fresh proof; a committed result carries its published entry UUID.

Authority: oboAccess + appId or oboAccess + appId + testingEnvironmentKey.

Request: application/json (required).

Cancel unpublished private staging#

POST /obo/uploads/cancel · cancelDelegatedUpload

Register briefcase.uploads.cancel at /api/v1/obo/uploads/cancel. Use a fresh proof for the exact JSON body and empty metadata. Cancellation revokes further staging and publication, with durable provider cleanup. Cleanup may remain pending while a writer lease or ambiguous provider operation is reconciled. Cancellation never deletes a published file; use the separately authorized trash operation for that.

Authority: oboAccess + appId or oboAccess + appId + testingEnvironmentKey.

Request: application/json (required).

Transfer exact private bytes using a narrow upload capability#

PUT /obo/uploads/{upload_id}/content · transferDelegatedUpload

Sends only the capability issued by the fresh-authorized reservation, the organization selector and the same test root when using a test plane. Do not send an IAM bearer, proof or application credential. Content-Length and the raw bytes must match the reserved size; the complete SHA-256 is checked before provider writes. A successful transfer is private staging only, not file publication. Use a fresh commit proof separately. A failed or uncertain transfer must be reconciled through the fresh-authorized status endpoint before retry.

Authority: uploadCapability or uploadCapability + testingEnvironmentKey.

Request: application/octet-stream (required).

Create a child folder for a represented member#

POST /obo/folders/create · createFolderOnBehalfOfMember

Register briefcase.folders.create at /api/v1/obo/folders/create with an empty IAM metadata schema. Mint a fresh proof for POST and the SHA-256 of the exact JSON body. No bearer credential accompanies the proof. Every input, including the logical operation UUID, is body-bound; query parameters and Idempotency-Key do not select them. An empty parent_path selects the represented member's private folder for the originating application. Otherwise the path must resolve to an existing folder. Ordinary write permission is required, and the created folder retains its originating application for auditing. Retry an uncertain result with the same operation_id and unchanged input, but a fresh proof. Authorization is checked again before replay.

Authority: oboAccess + appId or oboAccess + appId + testingEnvironmentKey.

Request: application/json (required).

List the represented member's visible entries#

POST /obo/entries/list · listEntriesOnBehalfOfMember

Register briefcase.entries.list at /api/v1/obo/entries/list with an empty IAM metadata schema. Each page requires a fresh proof bound to POST and the exact JSON body digest. The ordinary entry-list semantics apply, including traversal-only folders, privacy-filtered results, filters and opaque pagination. A parent can be addressed by UUID or path, never both. Omission lists roots, or searches the visible tree when a filter is present. No query parameter changes the request.

Authority: oboAccess + appId or oboAccess + appId + testingEnvironmentKey.

Request: application/json (required).

Stream a file for a represented member#

POST /obo/files/read · readFileOnBehalfOfMember

Register briefcase.files.read at /api/v1/obo/files/read with an empty IAM metadata schema. Mint a fresh proof for POST and the exact JSON body digest. Ordinary read/download authorization applies. Only the body-bound range and download flag control delivery; an HTTP Range header or query parameter cannot override them. Inline content uses the normal sandbox CSP, nosniff and private no-store response headers. Attachment content is served as application/octet-stream. The proof's authority applies only to this file request and is never cached.

Authority: oboAccess + appId or oboAccess + appId + testingEnvironmentKey.

Request: application/json (required).

Move an application-created entry to the recoverable bin#

POST /obo/entries/trash · trashEntryOnBehalfOfMember

Register briefcase.entries.trash at /api/v1/obo/entries/trash with an empty IAM metadata schema. Mint a fresh proof for POST and the SHA-256 of the exact JSON body. The represented member must currently have delete authority across the subtree, and the originating application may delete only entries it created. System containers cannot be deleted. Retry an uncertain result with the same operation_id and entry_id but a fresh proof; current authority is rechecked before recognizing the same completed deletion. A successful old key cannot delete an entry that has since been restored. This is recoverable deletion with normal retention, not permanent removal.

Authority: oboAccess + appId or oboAccess + appId + testingEnvironmentKey.

Request: application/json (required).

listVersions#

GET /entries/{entry_id}/versions · listVersions

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

restoreVersion#

POST /entries/{entry_id}/versions/{version_id}/restore · restoreVersion

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Report the organization's consumption and limits, in bytes#

GET /usage · readOrganizationUsage

Answers how much space the organization is actually consuming — exact byte counts, never percentages, so a client renders whichever unit or proportion it prefers.

storage.used_bytes is what every retained version currently weighs, including versions of entries sitting in the bin, because those bytes are still stored. It falls as soon as content is really deleted. daily_uploads.used_bytes is what has been uploaded since the last midnight UTC, and resets_at is the next one.

Limits default to 100 GiB of uploads per UTC day and 1 PiB of storage, and either may be raised or lowered per organization, so the figures reported here are the ones actually in force.

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

List recoverable entries, newest deletion first#

GET /bin · listBin

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

restoreEntry#

POST /bin/{entry_id}/restore · restoreEntry

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

configureOrganizationBucket#

PUT /storage/configuration · configureOrganizationBucket

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Request: application/json (required).

Resolve the clean permanent URL of an entry#

GET /org/{org_id}/{path} · resolvePermanentUrl

The path segment mirrors the folder structure exactly, for example /org/tos/private/cos:tos/top_secret/this_secret.md. The organization segment must match X-Org-ID. Without disposition the entry and its effective access are returned; with disposition the file bytes are streamed. Anything the caller cannot read answers 404.

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

List current member and dynamic tag invitations#

GET /entries/{entry_id}/invitations · listInvitations

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Invite a current member by ID, verified email, or IAM tag#

POST /entries/{entry_id}/invitations · createInvitation

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Request: application/json (required).

Revoke a member or tag invitation#

DELETE /entries/{entry_id}/invitations/{grant_id} · revokeInvitation

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Read explicit and inherited anonymous access#

GET /entries/{entry_id}/link-access · readLinkAccess

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Set anyone-with-link read/download access#

PUT /entries/{entry_id}/link-access · setLinkAccess

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Request: application/json (required).

Read 365 days of file/folder logs, newest first#

GET /entries/{entry_id}/logs · listEntryLogs

Authority: bearerAuth or bearerAuth + testingEnvironmentKey.

Read or download a publicly shared file or folder#

GET /public/{org_id}/{path} · readPublicEntry

Authority: anonymous.

Critical IAM-approved operation inside the calling app subtree#

POST /obo/invitations · inviteOnBehalfOfMember

IAM binds POST, this exact versioned path, the exact body SHA-256, subject, organization, and calling application. Require critical user approval in the IAM endpoint catalog.

Authority: oboAccess + appId or oboAccess + appId + testingEnvironmentKey.

Request: application/json (required).

Critical IAM-approved operation inside the calling app subtree#

POST /obo/link-access · setLinkAccessOnBehalfOfMember

IAM binds POST, this exact versioned path, the exact body SHA-256, subject, organization, and calling application. Require critical user approval in the IAM endpoint catalog.

Authority: oboAccess + appId or oboAccess + appId + testingEnvironmentKey.

Request: application/json (required).