{ "openapi": "3.1.0", "info": { "title": "Atom Files Developer API", "version": "0.14.0", "description": "API access is not yet available. This specification records the intended public interface; existing Atom internal services use different contracts. The upload data plane, snapshot consistency boundary, OAuth consent flow, and webhook secret handoff require implementation and integration tests before release." }, "servers": [ { "url": "https://api.atomfiles.invalid", "description": "Non-working placeholder; no public API is deployed." } ], "x-atom-api-availability": "not-released", "tags": [ { "name": "Browse & search" }, { "name": "Files & delivery" }, { "name": "File intelligence" }, { "name": "Organize" }, { "name": "Write & track" }, { "name": "Changes & events" }, { "name": "Access" }, { "name": "Usage & billing" } ], "security": [ { "ScopedBearer": [] } ], "paths": { "/v1/roots": { "get": { "tags": [ "Browse & search" ], "operationId": "listRoots", "summary": "List the folder roots this caller may enter, not every folder in the account.", "description": "**Where browsing starts.** `GET /v1/roots` returns only folders this token can enter: owned roots, shared folders, and accessible connected sources. A shared folder may be deep in its owner’s tree; private ancestors stay hidden. App labels such as PRIVATE, SHARED, and SOURCES are not folder IDs. Open a returned root with `GET /v1/folders/{folder_id}/children`.\n\n**How pages work.** Both routes return `items` and `next_cursor`. Follow `next_cursor` until it is null. Keep the same `sort` while paging (`name_asc` by default, or `modified_desc`); changing sort starts a new listing. An item ID breaks ties. Folder children contain files and folders in one sorted list.\n\n**What if things change?** Browsing is live. For example, if page one ends at M and Zebra is renamed Apple before page two, Apple may be missed because it moved before the cursor. De-duplicate by item ID and refresh after change notifications. Offline or connected-source edits appear only after their metadata syncs.\n\n**When to use a snapshot.** Use `GET /v1/changes/snapshot` when starting a sync client that needs a complete metadata inventory. All its pages describe the same point-in-time view of metadata Atom has already indexed; the final page returns a cursor for subsequent changes. This does not lock the tree, include unsynced edits, or capture file bytes. Every request still checks current access, so revocation takes effect even if an older cursor exists. Reference: /reference/folders/list/.", "x-atom-required-capability": "files.metadata.read", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "folder" ] }, "name": { "type": "string" }, "root_kind": { "type": "string", "enum": [ "owned", "shared", "source" ] }, "modified_at": { "type": "string", "format": "date-time" }, "grant_id": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "name", "root_kind", "modified_at", "grant_id" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ] }, "example": { "items": [ { "id": "folder_private", "type": "folder", "name": "My files", "root_kind": "owned", "modified_at": "2026-10-20T18:00:00Z", "grant_id": null }, { "id": "folder_123", "type": "folder", "name": "Projects", "root_kind": "shared", "modified_at": "2026-10-19T18:00:00Z", "grant_id": "grant_123" } ], "next_cursor": null } } } }, "400": { "description": "Invalid limit, sort, or pagination cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Pagination cursor expired; restart this listing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200; defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "name_asc (default) or modified_desc.", "schema": { "type": "string", "enum": [ "name_asc", "modified_desc" ], "default": "name_asc" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next-page cursor bound to this caller and sort order.", "schema": { "type": "string" } } ] } }, "/v1/folders/{folder_id}": { "get": { "tags": [ "Browse & search" ], "operationId": "getFolder", "summary": "Read one folder’s name, visible parent, revision, and effective access role.", "description": "Use one role rather than a stored list of action flags: viewer can browse and read; editor can also add, edit, and remove items inside the folder; owner can additionally rename, move, or trash the folder and manage sharing. The API derives permitted actions from this role and checks token scopes separately. A folder ID never bypasses a grant. A null parent_id means no parent is visible to this caller; it does not prove the folder is the owner’s top-level folder. Reference: /reference/folders/metadata/.", "x-atom-required-capability": "files.metadata.read", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "parent_id": { "type": [ "string", "null" ] }, "revision": { "type": "string" }, "access_role": { "type": "string", "enum": [ "viewer", "editor", "owner" ] } }, "required": [ "id", "name", "parent_id", "revision", "access_role" ] }, "example": { "id": "folder_123", "name": "Projects", "parent_id": null, "revision": "rev_007", "access_role": "editor" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Folder does not exist or is not visible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "folder_id", "in": "path", "required": true, "description": "Stable Atom folder ID.", "schema": { "type": "string" } } ] } }, "/v1/folders/{folder_id}/children": { "get": { "tags": [ "Browse & search" ], "operationId": "listFolderChildren", "summary": "List one visible folder’s immediate files and subfolders.", "description": "This returns only immediate children, not a recursive tree. It uses the same limit, sort, cursor, items, and next_cursor contract as /v1/roots. Files and folders share one order; the stable item ID breaks ties.\n\nA cursor continues this caller’s listing of this folder in the chosen sort order. A new sort starts at page one. Pages are live, so a concurrent move or rename may shift an item across a page boundary. Access is checked again on every page; an old cursor does not preserve a revoked grant. For a fixed metadata inventory, use /v1/changes/snapshot rather than this browsing endpoint. Reference: /reference/folders/children/.", "x-atom-required-capability": "files.metadata.read", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "file", "folder" ] }, "name": { "type": "string" }, "modified_at": { "type": "string", "format": "date-time" }, "version_id": { "type": "string", "description": "Present for files with a current content version; absent for folders." }, "availability": { "type": "string", "description": "Present for files; absent for folders." } }, "required": [ "id", "type", "name", "modified_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ] }, "example": { "items": [ { "id": "file_789", "type": "file", "name": "invoice.pdf", "modified_at": "2026-10-20T18:00:00Z", "version_id": "ver_012", "availability": "available" }, { "id": "folder_124", "type": "folder", "name": "Receipts", "modified_at": "2026-10-19T18:00:00Z" } ], "next_cursor": null } } } }, "400": { "description": "Invalid limit, sort, or pagination cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Folder does not exist or is not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Pagination cursor expired; restart this folder listing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "folder_id", "in": "path", "required": true, "description": "Visible folder ID from a root or prior children page.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–200; defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "name_asc (default) or modified_desc.", "schema": { "type": "string", "enum": [ "name_asc", "modified_desc" ], "default": "name_asc" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque next-page cursor bound to this folder, caller, and sort order.", "schema": { "type": "string" } } ] } }, "/v1/search": { "get": { "tags": [ "Browse & search" ], "operationId": "searchFiles", "summary": "Search authorized names and selected metadata; results may lag indexing.", "description": "Search authorized names and selected metadata; results may lag indexing. Reference: /reference/search/.", "x-atom-required-capability": "files.metadata.read", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "parent_id": { "type": "string" }, "version_id": { "type": "string" } }, "required": [ "id", "name", "parent_id", "version_id" ] } }, "next_cursor": { "type": [ "string", "null" ] }, "indexed_through": { "type": "string", "format": "date-time" } }, "required": [ "items", "next_cursor", "indexed_through" ] }, "example": { "items": [ { "id": "file_789", "name": "invoice.pdf", "parent_id": "folder_123", "version_id": "ver_012" } ], "next_cursor": null, "indexed_through": "2026-10-20T18:00:00Z" } } } }, "400": { "description": "Invalid query, filter, or cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search text.", "schema": { "type": "string" } }, { "name": "parent_id", "in": "query", "required": false, "description": "Limit search to an authorized folder.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor.", "schema": { "type": "string" } } ] } }, "/v1/files/{file_id}": { "get": { "tags": [ "Files & delivery" ], "operationId": "getFile", "summary": "Read stable file metadata without exposing device paths or provider credentials.", "description": "Read stable file metadata without exposing device paths or provider credentials. Reference: /reference/files/metadata/.", "x-atom-required-capability": "files.metadata.read", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "parent_id": { "type": "string" }, "name": { "type": "string" }, "media_type": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" }, "current_version_id": { "type": "string" }, "availability": { "type": "string" } }, "required": [ "id", "parent_id", "name", "media_type", "size_bytes", "current_version_id", "availability" ] }, "example": { "id": "file_789", "parent_id": "folder_123", "name": "invoice.pdf", "media_type": "application/pdf", "size_bytes": 4194304, "current_version_id": "ver_012", "availability": "available" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File does not exist or is not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "Stable Atom file ID.", "schema": { "type": "string" } } ] } }, "/v1/files/{file_id}/content": { "get": { "tags": [ "Files & delivery" ], "operationId": "getFileContent", "summary": "Stream a complete immutable version or a byte range. The route does not promise a particular P2P or cloud transport.", "description": "Stream a complete immutable version or a byte range. The route does not promise a particular P2P or cloud transport. Reference: /reference/files/content/.", "x-atom-required-capability": "files.content.read", "responses": { "200": { "description": "Complete selected version.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "application/octet-stream": { "schema": {} } } }, "206": { "description": "Byte range from the selected version.", "headers": { "Accept-Ranges": { "schema": { "type": "string" }, "description": "bytes" }, "Content-Range": { "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" }, "description": "Immutable version tag." } }, "content": { "application/octet-stream": { "schema": {} } } }, "400": { "description": "Invalid version or request syntax.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File or pinned version does not exist or is not visible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "416": { "description": "Requested bytes fall outside the pinned version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "Stable Atom file ID.", "schema": { "type": "string" } }, { "name": "version_id", "in": "query", "required": false, "description": "Pin bytes to one immutable version.", "schema": { "type": "string" } }, { "name": "Range", "in": "header", "required": false, "description": "Byte range for preview, seek, or resume.", "schema": { "type": "string" } }, { "name": "If-Range", "in": "header", "required": false, "description": "Only resume when the version still matches.", "schema": { "type": "string" } } ], "x-atom-release-dependency": "Range and If-Range behavior, cache policy, and media-player interoperability require contract tests." } }, "/v1/files/{file_id}/versions": { "get": { "tags": [ "Files & delivery" ], "operationId": "listFileVersions", "summary": "List versions visible to this caller for history and conflict resolution.", "description": "List versions visible to this caller for history and conflict resolution. Reference: /reference/files/versions/.", "x-atom-required-capability": "files.metadata.read", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "file_id": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "file_id", "size_bytes", "created_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ] }, "example": { "items": [ { "id": "ver_012", "file_id": "file_789", "size_bytes": 4194304, "created_at": "2026-10-20T18:00:00Z" } ], "next_cursor": null } } } }, "400": { "description": "Invalid pagination cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File does not exist or is not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "Stable Atom file ID.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor.", "schema": { "type": "string" } } ] } }, "/v1/files/{file_id}/processing": { "get": { "tags": [ "File intelligence" ], "operationId": "getFileProcessing", "summary": "Read detected file type and per-output processing progress for a content version.", "description": "There is no single file-wide complete flag. Every enabled output reports its own state: not_applicable, disabled, queued, running, partial, ready, failed, or stale. A new file version has independent processing state; old results must not appear current. Reference: /reference/intelligence/processing/.", "x-atom-required-capability": "files.analysis.read", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "file_id": { "type": "string" }, "version_id": { "type": "string" }, "policy_revision": { "type": "string" }, "detected_type": { "type": "object", "properties": { "media_type": { "type": "string" }, "family": { "type": "string", "x-atom-extensible-values": [ "image", "audio", "video", "document", "spreadsheet" ], "description": "Examples only; this value set can grow without an API version change." }, "detection": { "type": "string" } }, "required": [ "media_type", "family", "detection" ] }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "x-atom-extensible-values": [ "thumbnail", "page_ocr", "transcript", "page_summary", "document_summary", "visual_embedding" ], "description": "Examples only; this value set can grow without an API version change." }, "state": { "type": "string", "enum": [ "not_applicable", "disabled", "queued", "running", "partial", "ready", "failed", "stale" ] }, "completed_units": { "type": "integer", "format": "int64" }, "total_units": { "type": "integer", "format": "int64" }, "artifact_count": { "type": "integer", "format": "int64" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "kind", "state", "completed_units", "total_units", "artifact_count", "updated_at" ] } } }, "required": [ "file_id", "version_id", "policy_revision", "detected_type", "outputs" ] }, "example": { "file_id": "file_789", "version_id": "ver_012", "policy_revision": "proc_rev_007", "detected_type": { "media_type": "application/pdf", "family": "document", "detection": "content_and_metadata" }, "outputs": [ { "kind": "page_ocr", "state": "ready", "completed_units": 12, "total_units": 12, "artifact_count": 12, "updated_at": "2026-10-20T18:02:00Z" }, { "kind": "page_summary", "state": "partial", "completed_units": 4, "total_units": 12, "artifact_count": 4, "updated_at": "2026-10-20T18:03:00Z" }, { "kind": "document_summary", "state": "queued", "completed_units": 0, "total_units": 1, "artifact_count": 0, "updated_at": "2026-10-20T18:03:00Z" } ] } } } }, "400": { "description": "Invalid version ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File or version is not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "Stable Atom file ID.", "schema": { "type": "string" } }, { "name": "version_id", "in": "query", "required": false, "description": "Pin the processing report to an immutable content version.", "schema": { "type": "string" } } ] } }, "/v1/files/{file_id}/processing-policy": { "patch": { "tags": [ "File intelligence" ], "operationId": "updateFileProcessingPolicy", "summary": "Update which post-processing outputs are enabled for a file.", "description": "This is an owner-authorized, expected-revision change. Disabling an output stops future automatic generation but does not silently erase existing artifacts; use artifact deletion for removal. Sensitive analysis such as face detection requires separate explicit owner consent. Reference: /reference/intelligence/processing-policy/.", "x-atom-required-capability": "files.analysis.manage", "responses": { "202": { "description": "202 Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation_id": { "type": "string" }, "file_id": { "type": "string" }, "status": { "type": "string" }, "expected_policy_revision": { "type": "string" } }, "required": [ "operation_id", "file_id", "status", "expected_policy_revision" ] }, "example": { "operation_id": "op_601", "file_id": "file_789", "status": "accepted", "expected_policy_revision": "proc_rev_007" } } } }, "400": { "description": "Invalid output kind or policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File is not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Policy revision changed or idempotency key was reused with different input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "Stable Atom file ID.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable retry identity.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_policy_revision": { "type": "string" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "x-atom-extensible-values": [ "thumbnail", "page_ocr", "transcript", "page_summary", "document_summary", "face_detection" ], "description": "Examples only; this value set can grow without an API version change." }, "enabled": { "type": "boolean" } }, "required": [ "kind", "enabled" ] } } }, "required": [ "expected_policy_revision", "outputs" ] }, "example": { "expected_policy_revision": "proc_rev_007", "outputs": [ { "kind": "page_summary", "enabled": false } ] } } } } } }, "/v1/files/{file_id}/processing-runs": { "post": { "tags": [ "File intelligence" ], "operationId": "createProcessingRun", "summary": "Start or rerun selected enabled processors for one immutable version.", "description": "This creates a retry-safe run, not a new file version. A disabled processor cannot be started through this endpoint. Regenerated artifacts receive new IDs and retain provenance; an old result is not overwritten in place. Reference: /reference/intelligence/run/.", "x-atom-required-capability": "files.analysis.manage", "responses": { "202": { "description": "202 Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string" }, "file_id": { "type": "string" }, "version_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "cancellation_requested", "completed", "partially_completed", "failed", "cancelled" ] }, "status_url": { "type": "string" } }, "required": [ "run_id", "file_id", "version_id", "status", "status_url" ] }, "example": { "run_id": "run_123", "file_id": "file_789", "version_id": "ver_012", "status": "queued", "status_url": "/v1/processing-runs/run_123" } } } }, "400": { "description": "Invalid source version or output kinds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File or version is not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Requested output is disabled or the idempotency key was reused with different input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "Stable Atom file ID.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable retry identity; retrying must return the same run.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version_id": { "type": "string" }, "outputs": { "type": "array", "items": { "type": "string", "x-atom-extensible-values": [ "thumbnail", "page_ocr", "transcript", "document_summary" ], "description": "Examples only; this value set can grow without an API version change." } } }, "required": [ "version_id", "outputs" ] }, "example": { "version_id": "ver_012", "outputs": [ "page_ocr", "document_summary" ] } } } } } }, "/v1/processing-runs/{run_id}": { "get": { "tags": [ "File intelligence" ], "operationId": "getProcessingRun", "summary": "Inspect per-output progress and terminal outcome of a processing run.", "description": "A run may be queued, running, cancellation_requested, completed, partially_completed, failed, or cancelled. Published outputs are listed separately from the run status and remain available unless explicitly removed. Reference: /reference/intelligence/run-status/.", "x-atom-required-capability": "files.analysis.read", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "file_id": { "type": "string" }, "version_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "cancellation_requested", "completed", "partially_completed", "failed", "cancelled" ] }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "state": { "type": "string", "enum": [ "not_applicable", "disabled", "queued", "running", "partial", "ready", "failed", "stale" ] }, "completed_units": { "type": "integer", "format": "int64" }, "total_units": { "type": "integer", "format": "int64" } }, "required": [ "kind", "state", "completed_units", "total_units" ] } }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "file_id", "version_id", "status", "outputs", "updated_at" ] }, "example": { "id": "run_123", "file_id": "file_789", "version_id": "ver_012", "status": "running", "outputs": [ { "kind": "page_ocr", "state": "ready", "completed_units": 12, "total_units": 12 }, { "kind": "document_summary", "state": "running", "completed_units": 0, "total_units": 1 } ], "updated_at": "2026-10-20T18:04:00Z" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run is not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "run_id", "in": "path", "required": true, "description": "Processing run returned by the create request.", "schema": { "type": "string" } } ] } }, "/v1/processing-runs/{run_id}/cancel": { "post": { "tags": [ "File intelligence" ], "operationId": "cancelProcessingRun", "summary": "Request cancellation of remaining processing work.", "description": "Cancellation is a race with completion. It does not roll back outputs already published; inspect the run and artifact list afterward. Retrying with the same key must not create a second cancellation. Reference: /reference/intelligence/run-cancel/.", "x-atom-required-capability": "files.analysis.manage", "responses": { "202": { "description": "202 Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "cancellation_requested", "completed", "partially_completed", "failed", "cancelled" ] }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "run_id", "status", "updated_at" ] }, "example": { "run_id": "run_123", "status": "cancellation_requested", "updated_at": "2026-10-20T18:04:05Z" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Run is not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Run is already terminal; inspect its final status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "run_id", "in": "path", "required": true, "description": "Existing processing run.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable retry identity for the cancellation.", "schema": { "type": "string" } } ] } }, "/v1/files/{file_id}/artifacts": { "get": { "tags": [ "File intelligence" ], "operationId": "listFileArtifacts", "summary": "List derived outputs for an authorized file version.", "description": "Outputs may include thumbnails, OCR, transcripts, SRT/WebVTT captions, extracted images, page or document summaries, and structured tables. Availability depends on file type and processing policy. Every artifact identifies its source version and processor. Reference: /reference/intelligence/artifacts/.", "x-atom-required-capability": "files.analysis.read", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "file_id": { "type": "string" }, "version_id": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "x-atom-extensible-values": [ "thumbnail", "page_ocr", "transcript", "captions_srt", "captions_vtt", "document_summary", "structured_table" ], "description": "Examples only; this value set can grow without an API version change." }, "media_type": { "type": "string" }, "page_number": { "type": "integer", "format": "int64" }, "source_version_id": { "type": "string" }, "processor_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "start_ms": { "type": "integer", "format": "int64", "minimum": 0, "description": "Optional start of a time-coded segment." }, "end_ms": { "type": "integer", "format": "int64", "minimum": 0, "description": "Optional end of a time-coded segment." } }, "required": [ "id", "kind", "media_type", "source_version_id", "processor_id", "created_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "file_id", "version_id", "items", "next_cursor" ] }, "example": { "file_id": "file_789", "version_id": "ver_012", "items": [ { "id": "art_123", "kind": "page_ocr", "media_type": "text/plain", "page_number": 1, "source_version_id": "ver_012", "processor_id": "atom-ocr-v1", "created_at": "2026-10-20T18:02:00Z" } ], "next_cursor": null } } } }, "400": { "description": "Invalid version, kind, or cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File or version is not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "Stable Atom file ID.", "schema": { "type": "string" } }, { "name": "version_id", "in": "query", "required": false, "description": "Limit results to an immutable content version.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "Output kind, such as page_ocr, transcript, thumbnail, or document_summary.", "schema": { "type": "string", "x-atom-extensible-values": [ "thumbnail", "page_ocr", "transcript", "document_summary", "structured_table" ], "description": "Examples only; this value set can grow without an API version change." } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor bound to the selected version and filters.", "schema": { "type": "string" } } ] } }, "/v1/artifacts/{artifact_id}/content": { "get": { "tags": [ "File intelligence" ], "operationId": "getArtifactContent", "summary": "Read one derived output with its actual content type.", "description": "Authorization is checked against the source file on every read. A known artifact ID never bypasses a revoked folder grant. Large artifacts may support byte ranges; this route never returns underlying provider credentials or device paths. Reference: /reference/intelligence/artifact-content/.", "x-atom-required-capability": "files.analysis.read", "responses": { "200": { "description": "Complete derived artifact.", "headers": { "ETag": { "schema": { "type": "string" } } }, "content": { "text/plain": { "schema": {} }, "text/markdown": { "schema": {} }, "text/vtt": { "schema": {} }, "application/x-subrip": { "schema": {} }, "application/json": { "schema": {} }, "image/png": { "schema": {} }, "application/vnd.apache.parquet": { "schema": {} }, "application/octet-stream": { "schema": {} } } }, "206": { "description": "Byte range from the derived artifact.", "headers": { "Accept-Ranges": { "schema": { "type": "string" }, "description": "bytes" }, "Content-Range": { "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" }, "description": "Immutable artifact tag." } }, "content": { "text/plain": { "schema": {} }, "text/markdown": { "schema": {} }, "text/vtt": { "schema": {} }, "application/x-subrip": { "schema": {} }, "application/json": { "schema": {} }, "image/png": { "schema": {} }, "application/vnd.apache.parquet": { "schema": {} }, "application/octet-stream": { "schema": {} } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Artifact is absent or its source file is not visible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "416": { "description": "Requested bytes fall outside the artifact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "description": "Stable derived-artifact ID.", "schema": { "type": "string" } }, { "name": "Range", "in": "header", "required": false, "description": "Optional byte range for large derived outputs.", "schema": { "type": "string" } } ], "x-atom-release-dependency": "Artifact MIME types, source-file authorization, and optional range behavior require contract tests." } }, "/v1/artifacts/{artifact_id}": { "delete": { "tags": [ "File intelligence" ], "operationId": "deleteArtifact", "summary": "Purge a derived output without deleting its source file.", "description": "New artifact reads and search results are denied immediately; byte and vector removal completes asynchronously and is confirmed by the operation receipt. Automatic regeneration of this artifact is suppressed for its source version until an explicitly authorized rerun. Dependent projections must be invalidated. Reference: /reference/intelligence/artifact-delete/.", "x-atom-required-capability": "files.analysis.manage", "responses": { "202": { "description": "202 Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation_id": { "type": "string" }, "artifact_id": { "type": "string" }, "status": { "type": "string" }, "source_version_id": { "type": "string" } }, "required": [ "operation_id", "artifact_id", "status", "source_version_id" ] }, "example": { "operation_id": "op_602", "artifact_id": "art_123", "status": "purging", "source_version_id": "ver_012" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Artifact is absent or not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Artifact purge conflicts with another operation or retry identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "description": "Derived artifact to remove.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable retry identity.", "schema": { "type": "string" } } ] } }, "/v1/files/{file_id}/embeddings": { "get": { "tags": [ "File intelligence" ], "operationId": "listFileEmbeddings", "summary": "Read version-pinned vector representations for authorized file segments.", "description": "Raw vectors need an additional embeddings.read grant; normal file-read permission is insufficient. Results identify model, dimensions, source artifact, and page or time segment. The four-dimensional vector shown is illustrative, not a production model. Reference: /reference/intelligence/embeddings/.", "x-atom-required-capability": "embeddings.read", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "file_id": { "type": "string" }, "version_id": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "artifact_id": { "type": "string" }, "source_kind": { "type": "string", "x-atom-extensible-values": [ "page_ocr", "caption", "document", "frame", "audio_segment" ], "description": "Examples only; this value set can grow without an API version change." }, "page_number": { "type": "integer", "format": "int64" }, "model_id": { "type": "string" }, "dimensions": { "type": "integer", "format": "int64" }, "values": { "type": "array", "items": { "type": "number" } }, "created_at": { "type": "string", "format": "date-time" }, "start_ms": { "type": "integer", "format": "int64", "minimum": 0, "description": "Optional start of a time-coded segment." }, "end_ms": { "type": "integer", "format": "int64", "minimum": 0, "description": "Optional end of a time-coded segment." } }, "required": [ "id", "source_kind", "model_id", "dimensions", "values", "created_at" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "file_id", "version_id", "items", "next_cursor" ] }, "example": { "file_id": "file_789", "version_id": "ver_012", "items": [ { "id": "emb_123", "artifact_id": "art_123", "source_kind": "page_ocr", "page_number": 1, "model_id": "example-only-vector-4", "dimensions": 4, "values": [ 0.12, -0.04, 0.31, 0.07 ], "created_at": "2026-10-20T18:02:10Z" } ], "next_cursor": null } } } }, "400": { "description": "Invalid version, model, or cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "File or version is not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "file_id", "in": "path", "required": true, "description": "Stable Atom file ID.", "schema": { "type": "string" } }, { "name": "version_id", "in": "query", "required": false, "description": "Pin vectors to an immutable content version.", "schema": { "type": "string" } }, { "name": "model_id", "in": "query", "required": false, "description": "Select a compatible embedding model.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor.", "schema": { "type": "string" } } ] } }, "/v1/search/semantic": { "post": { "tags": [ "File intelligence" ], "operationId": "semanticSearch", "summary": "Find relevant file segments across authorized content.", "description": "Results are version-pinned and filtered by current access grants at query time. Report index freshness; incomplete processing means an incomplete result set. Search does not disclose content from revoked or trashed files. Reference: /reference/intelligence/semantic-search/.", "x-atom-required-capability": "files.analysis.read", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "file_id": { "type": "string" }, "version_id": { "type": "string" }, "artifact_id": { "type": "string" }, "source_kind": { "type": "string", "x-atom-extensible-values": [ "page_ocr", "caption", "document", "frame", "audio_segment" ], "description": "Examples only; this value set can grow without an API version change." }, "page_number": { "type": "integer", "format": "int64" }, "snippet": { "type": "string" }, "score": { "type": "number" }, "model_id": { "type": "string" }, "start_ms": { "type": "integer", "format": "int64", "minimum": 0, "description": "Optional start of a time-coded segment." }, "end_ms": { "type": "integer", "format": "int64", "minimum": 0, "description": "Optional end of a time-coded segment." } }, "required": [ "file_id", "version_id", "source_kind", "score", "model_id" ] } }, "indexed_through": { "type": "string", "format": "date-time" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "indexed_through", "next_cursor" ] }, "example": { "items": [ { "file_id": "file_789", "version_id": "ver_012", "artifact_id": "art_123", "source_kind": "page_ocr", "page_number": 1, "snippet": "Lease agreement signed by both parties", "score": 0.87, "model_id": "atom-text-v1" } ], "indexed_through": "2026-10-20T18:03:00Z", "next_cursor": null } } } }, "400": { "description": "Invalid query, scope, or limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "parent_id": { "type": "string" }, "limit": { "type": "integer", "format": "int64" } }, "required": [ "query" ] }, "example": { "query": "signed lease agreement", "parent_id": "folder_123", "limit": 10 } } } } } }, "/v1/folders": { "post": { "tags": [ "Organize" ], "operationId": "createFolder", "summary": "Create a child folder under an authorized parent using a retry-safe intent.", "description": "The operation becomes available only after its destination commits and returns a receipt. A lost response is recovered using the same Idempotency-Key. Reference: /reference/folders/create/.", "x-atom-required-capability": "files.write", "responses": { "202": { "description": "202 Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation_id": { "type": "string" }, "folder_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "operation_id", "folder_id", "status" ] }, "example": { "operation_id": "op_457", "folder_id": "folder_124", "status": "accepted" } } } }, "400": { "description": "Invalid name or parent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency key reused with different input or parent changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable retry identity.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parent_id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "parent_id", "name" ] }, "example": { "parent_id": "folder_123", "name": "Receipts" } } } } } }, "/v1/items/{item_id}": { "patch": { "tags": [ "Organize" ], "operationId": "updateItem", "summary": "Rename or move a file or folder using an expected metadata revision.", "description": "This endpoint changes metadata or placement, not immutable file bytes. An absent or stale expected revision must never silently overwrite a concurrent edit. Cross-provider moves may be asynchronous. Reference: /reference/items/update/.", "x-atom-required-capability": "files.write", "responses": { "202": { "description": "202 Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation_id": { "type": "string" }, "item_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "operation_id", "item_id", "status" ] }, "example": { "operation_id": "op_458", "item_id": "file_789", "status": "accepted" } } } }, "400": { "description": "Invalid name or destination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Item is not visible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Expected revision changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "item_id", "in": "path", "required": true, "description": "Stable file or folder ID.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable retry identity.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_revision": { "type": "string" }, "name": { "type": "string" }, "parent_id": { "type": "string" } }, "required": [ "expected_revision" ] }, "example": { "expected_revision": "rev_007", "name": "invoice-final.pdf", "parent_id": "folder_124" } } } } } }, "/v1/items/{item_id}/trash": { "post": { "tags": [ "Organize" ], "operationId": "trashItem", "summary": "Move a visible file or folder to recoverable trash; this is not permanent deletion.", "description": "An owner or appropriate writer must authorize the action. Existing shared recipients cannot delete the owner’s underlying bytes merely because they can read them. Retention and provider-specific behavior remain design decisions. Reference: /reference/items/trash/.", "x-atom-required-capability": "files.write", "responses": { "202": { "description": "202 Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation_id": { "type": "string" }, "item_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "operation_id", "item_id", "status" ] }, "example": { "operation_id": "op_459", "item_id": "file_789", "status": "accepted" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Item is not visible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Expected revision changed or item cannot be trashed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "item_id", "in": "path", "required": true, "description": "Stable file or folder ID.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable retry identity.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_revision": { "type": "string" } }, "required": [ "expected_revision" ] }, "example": { "expected_revision": "rev_008" } } } } } }, "/v1/items/{item_id}/restore": { "post": { "tags": [ "Organize" ], "operationId": "restoreItem", "summary": "Restore a trashed item into an authorized parent.", "description": "If the original parent no longer exists, the caller may choose another authorized folder. Restoration may conflict with a replacement name or expired retention. Reference: /reference/items/restore/.", "x-atom-required-capability": "files.write", "responses": { "202": { "description": "202 Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation_id": { "type": "string" }, "item_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "operation_id", "item_id", "status" ] }, "example": { "operation_id": "op_460", "item_id": "file_789", "status": "accepted" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Trashed item is not visible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Destination or retention state prevents restore.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "item_id", "in": "path", "required": true, "description": "Stable file or folder ID.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable retry identity.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parent_id": { "type": "string" } }, "required": [] }, "example": { "parent_id": "folder_123" } } } } } }, "/v1/uploads": { "post": { "tags": [ "Write & track" ], "operationId": "createUpload", "summary": "Create a retry-safe upload intent; acceptance is not a destination receipt.", "description": "Create a retry-safe upload intent; acceptance is not a destination receipt. Reference: /reference/uploads/create/.", "x-atom-required-capability": "files.write", "responses": { "202": { "description": "202 Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation_id": { "type": "string" }, "file_id": { "type": "string" }, "status": { "type": "string" }, "transfer": { "type": "object", "properties": { "method": { "type": "string" }, "capability": { "type": "string" } }, "required": [ "method", "capability" ] } }, "required": [ "operation_id", "file_id", "status", "transfer" ] }, "example": { "operation_id": "op_456", "file_id": "file_789", "status": "ready_to_transfer", "transfer": { "method": "direct", "capability": "" } } } } }, "400": { "description": "Invalid upload intent or file metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency key reused with different input, or expected version changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable retry identity for this upload intent.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parent_id": { "type": "string" }, "name": { "type": "string" }, "size_bytes": { "type": "integer", "format": "int64" }, "sha256": { "type": "string", "description": "Whole-file SHA-256 digest; exact wire encoding remains to be finalized." }, "replace_version_id": { "type": [ "string", "null" ] } }, "required": [ "parent_id", "name", "size_bytes", "sha256" ] }, "example": { "parent_id": "folder_123", "name": "invoice.pdf", "size_bytes": 4194304, "sha256": "", "replace_version_id": null } } } } } }, "/v1/uploads/{operation_id}/transfer-plan": { "post": { "tags": [ "Write & track" ], "operationId": "refreshUploadTransferPlan", "summary": "Refresh a short-lived transfer capability for the same upload operation.", "description": "Refreshing a plan must not create a second file. The data-plane protocol, acknowledged offsets, part sizes, capability binding, and resume semantics need integration tests before release. Reference: /reference/uploads/transfer-plan/.", "x-atom-required-capability": "files.write", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation_id": { "type": "string" }, "status": { "type": "string" }, "transfer": { "type": "object", "properties": { "method": { "type": "string" }, "capability": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "method", "capability", "expires_at" ] } }, "required": [ "operation_id", "status", "transfer" ] }, "example": { "operation_id": "op_456", "status": "ready_to_transfer", "transfer": { "method": "direct", "capability": "", "expires_at": "2026-10-20T18:10:00Z" } } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Operation is not visible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Operation cannot receive more bytes in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "operation_id", "in": "path", "required": true, "description": "Existing upload operation; do not create a second file.", "schema": { "type": "string" } } ], "x-atom-release-dependency": "Release-blocking semantics are identified in the matching reference page but not yet proven by a running service." } }, "/v1/uploads/{operation_id}/cancel": { "post": { "tags": [ "Write & track" ], "operationId": "cancelUpload", "summary": "Ask Atom to cancel an upload that has not committed.", "description": "Cancellation is retry-safe. It cannot undo a version already committed at the destination. Clients inspect the operation after an ambiguous acknowledgement. Reference: /reference/uploads/cancel/.", "x-atom-required-capability": "files.write", "responses": { "202": { "description": "202 Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "operation_id", "status" ] }, "example": { "operation_id": "op_456", "status": "cancelled" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Operation is not visible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Operation is already committed or terminal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "operation_id", "in": "path", "required": true, "description": "Existing upload operation.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable retry identity for cancellation.", "schema": { "type": "string" } } ] } }, "/v1/uploads/{operation_id}/finish": { "post": { "tags": [ "Write & track" ], "operationId": "finishUpload", "summary": "Report sender completion; the destination still verifies bytes and version conditions.", "description": "Report sender completion; the destination still verifies bytes and version conditions. Reference: /reference/uploads/finish/.", "x-atom-required-capability": "files.write", "responses": { "202": { "description": "202 Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "operation_id", "status" ] }, "example": { "operation_id": "op_456", "status": "verifying" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Operation does not exist or is not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Operation cannot be finished in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "operation_id", "in": "path", "required": true, "description": "Operation returned by create upload.", "schema": { "type": "string" } } ] } }, "/v1/operations/{operation_id}": { "get": { "tags": [ "Write & track" ], "operationId": "getOperation", "summary": "Recover authoritative state after a timeout or lost acknowledgement.", "description": "Recover authoritative state after a timeout or lost acknowledgement. Reference: /reference/operations/status/.", "x-atom-required-capability": "files.metadata.read", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "x-atom-extensible-values": [ "file_upload", "metadata_update", "processing_policy_update", "artifact_purge" ], "description": "Examples only; this value set can grow without an API version change." }, "file_id": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "completion_receipt": { "type": "object", "properties": { "kind": { "type": "string" }, "reference": { "type": "string" } }, "required": [ "kind", "reference" ], "description": "Present only after the operation completes with a durable destination or purge receipt." } }, "required": [ "id", "kind", "file_id", "status", "updated_at" ] }, "example": { "id": "op_456", "kind": "file_upload", "file_id": "file_789", "status": "available", "updated_at": "2026-10-20T18:00:00Z", "completion_receipt": { "kind": "destination_commit", "reference": "" } } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Operation does not exist or is not visible to this caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "operation_id", "in": "path", "required": true, "description": "Stable operation ID.", "schema": { "type": "string" } } ] } }, "/v1/changes": { "get": { "tags": [ "Changes & events" ], "operationId": "listChanges", "summary": "Read authorized metadata changes from an opaque replay cursor.", "description": "Read authorized metadata changes from an opaque replay cursor. Reference: /reference/changes/.", "x-atom-required-capability": "events.read", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "file_id": { "type": "string" }, "version_id": { "type": "string" } }, "required": [ "id", "type", "file_id", "version_id" ] } }, "next_cursor": { "type": "string" } }, "required": [ "items", "next_cursor" ] }, "example": { "items": [ { "id": "change_234", "type": "file.available", "file_id": "file_789", "version_id": "ver_012" } ], "next_cursor": "cursor_124" } } } }, "400": { "description": "Malformed cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Replay history expired; obtain a fresh authorized snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque checkpoint; omit for an authorized initial snapshot.", "schema": { "type": "string" } } ] } }, "/v1/changes/snapshot": { "get": { "tags": [ "Changes & events" ], "operationId": "getChangeSnapshot", "summary": "Bootstrap an authorized metadata snapshot and a cursor for subsequent changes.", "description": "Pagination must represent one consistent snapshot. The final page alone provides a resume_cursor that starts strictly after the snapshot boundary; an expired snapshot returns 410 and must restart. This ordering is a release-blocking invariant. Reference: /reference/changes/snapshot/.", "x-atom-required-capability": "events.read", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "snapshot_id": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "parent_id": { "type": "string" }, "version_id": { "type": "string" } }, "required": [ "id", "type", "parent_id", "version_id" ] } }, "next_cursor": { "type": [ "string", "null" ] }, "resume_cursor": { "type": "string", "description": "Present only on the final snapshot page; use it to start incremental changes." } }, "required": [ "snapshot_id", "items", "next_cursor" ] }, "example": { "snapshot_id": "snap_123", "items": [ { "id": "file_789", "type": "file", "parent_id": "folder_123", "version_id": "ver_012" } ], "next_cursor": null, "resume_cursor": "cursor_124" } } } }, "400": { "description": "Invalid snapshot cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Snapshot expired; restart from the first page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque next-page cursor from this snapshot.", "schema": { "type": "string" } } ], "x-atom-release-dependency": "Release-blocking semantics are identified in the matching reference page but not yet proven by a running service." } }, "/v1/webhooks": { "post": { "tags": [ "Changes & events" ], "operationId": "createWebhook", "summary": "Create a verified HTTPS subscription. Webhooks are hints, not the recovery source.", "description": "Create a verified HTTPS subscription. Webhooks are hints, not the recovery source. Reference: /reference/webhooks/.", "x-atom-required-capability": "webhooks.manage", "responses": { "201": { "description": "201 Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "status" ] }, "example": { "id": "wh_123", "status": "pending_verification" } } } }, "400": { "description": "Invalid receiver URL or event list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Equivalent webhook registration already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "event_types" ] }, "example": { "url": "https://example.app/atom/events", "event_types": [ "file.available", "file.version_created", "artifact.ready", "artifact.purged", "processing.failed", "processing.cancelled", "operation.failed", "access.revoked" ] } } } } }, "get": { "tags": [ "Changes & events" ], "operationId": "listWebhooks", "summary": "List this integration’s webhook subscriptions and verification status.", "description": "Do not return signing secrets after initial issuance or rotation. A webhook is only a notification hint; use the change feed for catch-up. Reference: /reference/webhooks/list/.", "x-atom-required-capability": "webhooks.manage", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "url", "status", "event_types" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ] }, "example": { "items": [ { "id": "wh_123", "url": "https://example.app/atom/events", "status": "active", "event_types": [ "file.available" ] } ], "next_cursor": null } } } }, "400": { "description": "Invalid pagination cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor.", "schema": { "type": "string" } } ] } }, "/v1/webhooks/{webhook_id}": { "delete": { "tags": [ "Changes & events" ], "operationId": "deleteWebhook", "summary": "Stop future deliveries to this integration’s receiver.", "description": "Deletion must be safe to retry. In-flight deliveries may still arrive and must remain verifiable during a documented overlap window. Reference: /reference/webhooks/delete/.", "x-atom-required-capability": "webhooks.manage", "responses": { "204": { "description": "No Content" }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook is not visible to this integration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "description": "Webhook owned by this integration.", "schema": { "type": "string" } } ] } }, "/v1/webhooks/{webhook_id}/rotate-secret": { "post": { "tags": [ "Changes & events" ], "operationId": "rotateWebhookSecret", "summary": "Start signing-secret rotation for a webhook without losing event delivery.", "description": "The exact one-time secret handoff, old/new overlap window, and lost-acknowledgement recovery are unresolved security decisions; this example intentionally does not return a secret. Reference: /reference/webhooks/rotate-secret/.", "x-atom-required-capability": "webhooks.manage", "responses": { "202": { "description": "202 Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "rotation_id": { "type": "string" } }, "required": [ "id", "status", "rotation_id" ] }, "example": { "id": "wh_123", "status": "rotating", "rotation_id": "rotation_123" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Webhook is not visible to this integration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Rotation already pending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "description": "Webhook owned by this integration.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable retry identity.", "schema": { "type": "string" } } ], "x-atom-release-dependency": "Release-blocking semantics are identified in the matching reference page but not yet proven by a running service." } }, "/v1/grants": { "get": { "tags": [ "Access" ], "operationId": "listGrants", "summary": "Let an owner inspect which integrations can access which folders.", "description": "Creating a grant belongs to an explicit interactive consent flow, not an unscoped service-token API. This endpoint must not reveal unrelated account grants to an integration. Reference: /reference/grants/list/.", "x-atom-required-capability": "account.owner", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "folder_id": { "type": "string" }, "integration_id": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" } }, "required": [ "id", "folder_id", "integration_id", "capabilities", "status" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ] }, "example": { "items": [ { "id": "grant_123", "folder_id": "folder_123", "integration_id": "app_123", "capabilities": [ "read", "write" ], "status": "active" } ], "next_cursor": null } } } }, "400": { "description": "Invalid pagination cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor.", "schema": { "type": "string" } } ] } }, "/v1/grants/{grant_id}": { "delete": { "tags": [ "Access" ], "operationId": "revokeGrant", "summary": "Revoke an integration’s folder grant.", "description": "New metadata and byte reads must be denied immediately at the API boundary. Offline replicas remove their local projection on reconnect; already-exported bytes cannot be remotely recalled. Reference: /reference/grants/revoke/.", "x-atom-required-capability": "account.owner", "responses": { "204": { "description": "No Content" }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Grant is not visible to this owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "grant_id", "in": "path", "required": true, "description": "Grant managed by the account owner.", "schema": { "type": "string" } } ] } }, "/v1/usage/summary": { "get": { "tags": [ "Usage & billing" ], "operationId": "getUsageSummary", "summary": "Summarize observed transfer activity separately from billable units.", "description": "Summarize observed transfer activity separately from billable units. Reference: /reference/usage/summary/.", "x-atom-required-capability": "usage.read", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "required": [ "from", "to" ] }, "status": { "type": "string" }, "observed_through": { "type": "string", "format": "date-time" }, "transfer_bytes": { "type": "object", "properties": { "direct_peer": { "type": "integer", "format": "int64" }, "relay": { "type": "integer", "format": "int64" }, "cloud_egress": { "type": "integer", "format": "int64" } }, "required": [ "direct_peer", "relay", "cloud_egress" ] }, "api_requests": { "type": "integer", "format": "int64" }, "billable": { "type": "array", "items": { "type": "object", "properties": { "meter": { "type": "string" }, "quantity": { "type": "integer", "format": "int64" }, "unit": { "type": "string" } }, "required": [ "meter", "quantity", "unit" ] } } }, "required": [ "period", "status", "observed_through", "transfer_bytes", "api_requests", "billable" ] }, "example": { "period": { "from": "2026-10-01", "to": "2026-11-01" }, "status": "estimated", "observed_through": "2026-10-20T18:00:00Z", "transfer_bytes": { "direct_peer": 104857600, "relay": 16777216, "cloud_egress": 0 }, "api_requests": 42, "billable": [ { "meter": "relay_egress_bytes", "quantity": 16777216, "unit": "byte" } ] } } } }, "400": { "description": "Invalid reporting period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Inclusive period start.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Exclusive period end.", "schema": { "type": "string", "format": "date" } } ] } }, "/v1/usage/events": { "get": { "tags": [ "Usage & billing" ], "operationId": "listUsageEvents", "summary": "Page through auditable metering events.", "description": "Page through auditable metering events. Reference: /reference/usage/events/.", "x-atom-required-capability": "usage.read", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "meter": { "type": "string" }, "quantity": { "type": "integer", "format": "int64" }, "unit": { "type": "string" }, "operation_id": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "meter", "quantity", "unit", "operation_id", "occurred_at" ] } }, "next_cursor": { "type": [ "string", "null" ] }, "observed_through": { "type": "string", "format": "date-time" } }, "required": [ "items", "next_cursor", "observed_through" ] }, "example": { "items": [ { "id": "usage_123", "meter": "relay_egress_bytes", "quantity": 16777216, "unit": "byte", "operation_id": "op_456", "occurred_at": "2026-10-20T18:00:00Z" } ], "next_cursor": null, "observed_through": "2026-10-20T18:00:00Z" } } } }, "400": { "description": "Invalid period, meter, or cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Period start.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Period end.", "schema": { "type": "string", "format": "date" } }, { "name": "meter", "in": "query", "required": false, "description": "Meter filter.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor.", "schema": { "type": "string" } } ] } }, "/v1/billing/summary": { "get": { "tags": [ "Usage & billing" ], "operationId": "getBillingSummary", "summary": "Read account-level estimated billing, separate from file authorization.", "description": "Read account-level estimated billing, separate from file authorization. Reference: /reference/billing/summary/.", "x-atom-required-capability": "billing.admin", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string" }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "required": [ "from", "to" ] }, "status": { "type": "string" }, "estimated_total_minor": { "type": "integer", "format": "int64" }, "observed_through": { "type": "string", "format": "date-time" } }, "required": [ "currency", "period", "status", "estimated_total_minor", "observed_through" ] }, "example": { "currency": "CAD", "period": { "from": "2026-10-01", "to": "2026-11-01" }, "status": "estimated", "estimated_total_minor": 1299, "observed_through": "2026-10-20T18:00:00Z" } } } }, "400": { "description": "Invalid billing period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "period", "in": "query", "required": false, "description": "Billing period; defaults to current period.", "schema": { "type": "string", "format": "date" } } ] } }, "/v1/billing/invoices": { "get": { "tags": [ "Usage & billing" ], "operationId": "listBillingInvoices", "summary": "List finalized invoices for an owner or billing administrator.", "description": "List finalized invoices for an owner or billing administrator. Reference: /reference/billing/invoices/.", "x-atom-required-capability": "billing.admin", "responses": { "200": { "description": "200 OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "currency": { "type": "string" }, "status": { "type": "string" }, "total_minor": { "type": "integer", "format": "int64" }, "hosted_url": { "type": "string" } }, "required": [ "id", "currency", "status", "total_minor", "hosted_url" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "next_cursor" ] }, "example": { "items": [ { "id": "inv_123", "currency": "CAD", "status": "paid", "total_minor": 1299, "hosted_url": "" } ], "next_cursor": null } } } }, "400": { "description": "Invalid pagination cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired, or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Credential is valid but lacks the required scope or role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached; honor Retry-After when provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service temporarily unavailable; retry safely.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor.", "schema": { "type": "string" } } ] } } }, "components": { "securitySchemes": { "ScopedBearer": { "type": "http", "scheme": "bearer", "description": "Folder- or account-scoped token. Public issuance and consent are not yet available." } }, "schemas": { "Error": { "type": "object", "description": "Error envelope to be finalized with the public API implementation.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }