{ "openapi": "3.0.0", "paths": { "/api/v1/health": { "get": { "description": "Liveness and the adapters in use. Also served at `/health` without the API prefix.", "operationId": "Health_health", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthBody" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "summary": "Health check", "tags": [ "Health" ], "x-audience": [ "public" ], "externalDocs": { "description": "API conventions", "url": "/reference/api-conventions/" } } }, "/api/v1/me": { "get": { "description": "Whether the Identity Server reports the `platform_admin` role for the caller (cached for the access TTL). The console shows the Platform administration panel from it.", "operationId": "Context_me", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `insufficient_scope`, `client_context_mismatch`, `principal_not_allowed`, `files_access_not_granted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "insufficient_scope", "message": "A user token lacks `files:access`, a machine token carries none of `files:manage`, `files:read`, `files:config.manage`, or the route needs a scope the token does not carry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Who the caller is", "tags": [ "Context" ], "x-audience": [ "user" ], "x-required-scopes": { "user": [ "files:access" ] }, "x-error-codes": [ "invalid_token", "insufficient_scope", "client_context_mismatch", "principal_not_allowed", "files_access_not_granted", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Contexts and tokens", "url": "/concepts/contexts-and-tokens/" } } }, "/api/v1/me/tenants": { "get": { "description": "The active tenants the caller belongs to. A client of a tenant application sees only its own tenant.", "operationId": "Context_tenants", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantList" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `insufficient_scope`, `client_context_mismatch`, `principal_not_allowed`, `files_access_not_granted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "insufficient_scope", "message": "A user token lacks `files:access`, a machine token carries none of `files:manage`, `files:read`, `files:config.manage`, or the route needs a scope the token does not carry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The caller's tenants", "tags": [ "Context" ], "x-audience": [ "user" ], "x-required-scopes": { "user": [ "files:access" ] }, "x-error-codes": [ "invalid_token", "insufficient_scope", "client_context_mismatch", "principal_not_allowed", "files_access_not_granted", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Contexts and tokens", "url": "/concepts/contexts-and-tokens/" } } }, "/api/v1/tenants/{tenant_id}/applications": { "get": { "description": "The tenant's active applications the caller has access to, with whether each switched Files off. A client of a tenant application sees only its own application; the console's own platform context is not listed.", "operationId": "Context_applications", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextApplicationList" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The applications the caller may use", "tags": [ "Context" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read", "files:config.manage" ] }, "x-membership-only": true, "x-error-codes": [ "invalid_token", "not_tenant_member", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Contexts and tokens", "url": "/concepts/contexts-and-tokens/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/me/capabilities": { "get": { "description": "The `files.*` keys the caller holds in the application (umbrellas expanded; the tenant owner holds every key; a machine client the keys of its scopes), with the caller's roles.", "operationId": "Capabilities_capabilities", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilitiesBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The caller's capabilities here", "tags": [ "Context" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read", "files:config.manage" ] }, "x-membership-only": true, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Contexts and tokens", "url": "/concepts/contexts-and-tokens/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/permissions": { "get": { "description": "The permission catalog and every role of the tenant that may carry it in this application, with the keys mapped onto each. Read live from the Identity Server.", "operationId": "ApplicationPermissions_list", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionsBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `principal_not_allowed`, `files_access_not_granted`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Who may do what with files here", "tags": [ "Permissions" ], "x-audience": [ "user" ], "x-required-scopes": { "user": [ "files:access" ] }, "x-required-capabilities": { "all": [ "files.permissions.manage" ] }, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "principal_not_allowed", "files_access_not_granted", "missing_capability", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions page", "url": "/administration/permissions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/permissions/roles/{role_id}": { "put": { "description": "An idempotent replace of the role's keys in this application, stored at the Identity Server on behalf of the caller. `tenant_owner` cannot be changed (`role_locked`); only the tenant owner may add or remove `files.permissions.manage` (`tenant_owner_required`). Takes effect within about a minute.", "operationId": "ApplicationPermissions_set", "parameters": [ { "name": "role_id", "required": true, "in": "path", "description": "An Identity Server role id.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetRolePermissionsBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RolePermissionsItemBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`, `role_locked`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `principal_not_allowed`, `files_access_not_granted`, `missing_capability`, `tenant_owner_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `role_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Replace a role's permissions here", "tags": [ "Permissions" ], "x-audience": [ "user" ], "x-required-scopes": { "user": [ "files:access" ] }, "x-required-capabilities": { "all": [ "files.permissions.manage" ] }, "x-error-codes": [ "invalid_request", "role_locked", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "principal_not_allowed", "files_access_not_granted", "missing_capability", "tenant_owner_required", "application_not_found", "not_found", "role_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions page", "url": "/administration/permissions/" } } }, "/api/v1/tenants/{tenant_id}/permissions": { "get": { "description": "The catalog and, per application the caller may use, whether it may manage its permissions and the roles with their keys.", "operationId": "TenantPermissions_list", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPermissionsBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `principal_not_allowed`, `files_access_not_granted`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `too_many_applications`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "too_many_applications", "message": "The tenant has more applications than one tenant-level read or write handles.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Who may do what with files, in every application", "tags": [ "Permissions" ], "x-audience": [ "user" ], "x-required-scopes": { "user": [ "files:access" ] }, "x-membership-only": true, "x-error-codes": [ "invalid_token", "not_tenant_member", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "principal_not_allowed", "files_access_not_granted", "missing_capability", "not_found", "too_many_applications", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions page", "url": "/administration/permissions/" } } }, "/api/v1/tenants/{tenant_id}/permissions/roles/{role_id}": { "put": { "description": "Writes the same key set into every application the caller manages, four at a time, and reports one result per application (`applied`, `failed`, `skipped`). Each application's write stands on its own; retrying is safe. Tenant roles only.", "operationId": "TenantPermissions_apply", "parameters": [ { "name": "role_id", "required": true, "in": "path", "description": "An Identity Server role id.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetRolePermissionsBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyRolePermissionsBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`, `role_locked`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `principal_not_allowed`, `files_access_not_granted`, `missing_capability`, `tenant_owner_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`, `role_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `too_many_applications`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "too_many_applications", "message": "The tenant has more applications than one tenant-level read or write handles.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Replace a tenant role's permissions in every application", "tags": [ "Permissions" ], "x-audience": [ "user" ], "x-required-scopes": { "user": [ "files:access" ] }, "x-membership-only": true, "x-error-codes": [ "invalid_request", "role_locked", "invalid_token", "not_tenant_member", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "principal_not_allowed", "files_access_not_granted", "missing_capability", "tenant_owner_required", "not_found", "role_not_found", "too_many_applications", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions page", "url": "/administration/permissions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/folders/root": { "get": { "description": "Exists implicitly per application; every member may view it (it lists only what each caller may see).", "operationId": "Folders_root", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderBody" }, "example": { "type": "folder", "folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "tenant_id": "fitness-co", "application_id": "fitness-app", "parent_id": "root", "name": "posts", "path": "/posts", "depth": 1, "description": null, "owner_id": "u-ana", "inherit": true, "acl_scope_id": "root", "entries_count": 0, "state": "available", "revision": 1, "metadata": {}, "managed": true, "managed_by": { "client_id": "fitness-backend", "name": "Fitness", "managed_folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "managed_at": "2026-10-22T09:12:33.120Z" }, "created_at": "2026-10-22T09:12:33.120Z", "updated_at": "2026-10-22T09:12:33.120Z", "trashed_at": null, "trashed_by": null, "my_actions": [ "view", "download", "edit", "share", "delete" ] } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The root folder", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Folders and files", "url": "/concepts/folders-and-files/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/folders/by-external-ref/{external_ref}": { "get": { "description": "The folders carrying `external_ref`, that the caller may view.", "operationId": "Folders_byExternalRef", "parameters": [ { "name": "external_ref", "required": true, "in": "path", "description": "The tenant's own reference, as set on the file (at most 200 characters).", "schema": { "type": "string" } }, { "name": "after", "required": false, "in": "query", "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderPageBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Folders by your reference", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Folders and files", "url": "/concepts/folders-and-files/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/folders": { "post": { "description": "Needs `edit` on the parent. Names are unique among siblings, compared case-insensitively. A machine client with `files:manage` may create it application-managed (`managed: true`): read-only for people with its whole subtree.", "operationId": "Folders_create", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Replays the first answer for 24 hours when the same key is sent again (1 to 200 characters).", "required": false, "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFolderBody" }, "example": { "parent_id": "root", "name": "posts", "external_ref": "posts", "managed": true } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderBody" }, "example": { "type": "folder", "folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "tenant_id": "fitness-co", "application_id": "fitness-app", "parent_id": "root", "name": "posts", "path": "/posts", "depth": 1, "description": null, "owner_id": "u-ana", "inherit": true, "acl_scope_id": "root", "entries_count": 0, "state": "available", "revision": 1, "metadata": {}, "managed": true, "managed_by": { "client_id": "fitness-backend", "name": "Fitness", "managed_folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "managed_at": "2026-10-22T09:12:33.120Z" }, "created_at": "2026-10-22T09:12:33.120Z", "updated_at": "2026-10-22T09:12:33.120Z", "trashed_at": null, "trashed_by": null, "my_actions": [ "view", "download", "edit", "share", "delete" ] } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`, `invalid_name`, `depth_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `folder_managed`, `principal_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `folder_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `name_conflict`, `folder_busy`, `file_trashed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "name_conflict", "message": "A sibling with the same name exists in the folder (names are compared case-insensitively).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a folder", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "edit", "x-error-codes": [ "invalid_request", "invalid_name", "depth_exceeded", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "folder_managed", "principal_not_allowed", "application_not_found", "not_found", "folder_not_found", "name_conflict", "folder_busy", "file_trashed", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Folders and files", "url": "/concepts/folders-and-files/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/folders/{folder_id}": { "get": { "operationId": "Folders_get", "parameters": [ { "name": "folder_id", "required": true, "in": "path", "description": "A folder id (ULID), or `root` for the application's root folder.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderBody" }, "example": { "type": "folder", "folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "tenant_id": "fitness-co", "application_id": "fitness-app", "parent_id": "root", "name": "posts", "path": "/posts", "depth": 1, "description": null, "owner_id": "u-ana", "inherit": true, "acl_scope_id": "root", "entries_count": 0, "state": "available", "revision": 1, "metadata": {}, "managed": true, "managed_by": { "client_id": "fitness-backend", "name": "Fitness", "managed_folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "managed_at": "2026-10-22T09:12:33.120Z" }, "created_at": "2026-10-22T09:12:33.120Z", "updated_at": "2026-10-22T09:12:33.120Z", "trashed_at": null, "trashed_by": null, "my_actions": [ "view", "download", "edit", "share", "delete" ] } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `folder_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "A folder", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "folder_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Folders and files", "url": "/concepts/folders-and-files/" } }, "patch": { "description": "A move needs `edit` on the source and the target; a large subtree is rewritten by a background job (the folder is `busy` meanwhile). A machine client with `files:manage` marks (`managed: true`) or unmarks (`managed: false`) an application-managed folder.", "operationId": "Folders_update", "parameters": [ { "name": "folder_id", "required": true, "in": "path", "description": "A folder id (ULID), or `root` for the application's root folder.", "schema": { "type": "string" } }, { "name": "if-match", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "description": "The `revision` you read; a stale one answers 412 `revision_mismatch`.", "required": false, "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFolderBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderBody" }, "example": { "type": "folder", "folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "tenant_id": "fitness-co", "application_id": "fitness-app", "parent_id": "root", "name": "posts", "path": "/posts", "depth": 1, "description": null, "owner_id": "u-ana", "inherit": true, "acl_scope_id": "root", "entries_count": 0, "state": "available", "revision": 1, "metadata": {}, "managed": true, "managed_by": { "client_id": "fitness-backend", "name": "Fitness", "managed_folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "managed_at": "2026-10-22T09:12:33.120Z" }, "created_at": "2026-10-22T09:12:33.120Z", "updated_at": "2026-10-22T09:12:33.120Z", "trashed_at": null, "trashed_by": null, "my_actions": [ "view", "download", "edit", "share", "delete" ] } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`, `invalid_name`, `invalid_move`, `depth_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `folder_managed`, `principal_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `folder_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `name_conflict`, `folder_busy`, `file_trashed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "name_conflict", "message": "A sibling with the same name exists in the folder (names are compared case-insensitively).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "412": { "description": "Error. `error` is one of: `revision_mismatch`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 412, "error": "revision_mismatch", "message": "The `If-Match` revision is stale: the item changed since it was read.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Rename, move or update a folder", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "edit", "x-error-codes": [ "invalid_request", "invalid_name", "invalid_move", "depth_exceeded", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "folder_managed", "principal_not_allowed", "application_not_found", "not_found", "folder_not_found", "name_conflict", "folder_busy", "file_trashed", "revision_mismatch", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Folders and files", "url": "/concepts/folders-and-files/" } }, "delete": { "description": "204 for an empty folder; 202 with the job for a subtree. Every item below needs `delete` (403 `partial_permission` lists what blocks).", "operationId": "Folders_remove", "parameters": [ { "name": "folder_id", "required": true, "in": "path", "description": "A folder id (ULID), or `root` for the application's root folder.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRefBody" } } } }, "204": { "description": "No content." }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `partial_permission`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `folder_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `folder_busy`, `file_trashed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "folder_busy", "message": "The folder's subtree is being moved or copied by a background job.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Move a folder to the trash", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "delete", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "partial_permission", "folder_managed", "application_not_found", "not_found", "folder_not_found", "folder_busy", "file_trashed", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Folders and files", "url": "/concepts/folders-and-files/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/folders/{folder_id}/children": { "get": { "description": "Folders first when sorted by name or size. Only the children the caller may view are listed, filtered inside the query so paging is exact.", "operationId": "Folders_children", "parameters": [ { "name": "folder_id", "required": true, "in": "path", "description": "A folder id (ULID), or `root` for the application's root folder.", "schema": { "type": "string" } }, { "name": "after", "required": false, "in": "query", "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "include_trashed", "required": false, "in": "query", "schema": { "type": "boolean" } }, { "name": "order", "required": false, "in": "query", "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "name": "sort", "required": false, "in": "query", "schema": { "enum": [ "name", "created_at", "updated_at", "size" ], "type": "string" } }, { "name": "type", "required": false, "in": "query", "schema": { "enum": [ "folders", "files", "all" ], "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChildrenBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`, `invalid_cursor`, `invalid_limit`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `folder_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "List a folder", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_request", "invalid_cursor", "invalid_limit", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "folder_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Folders and files", "url": "/concepts/folders-and-files/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/folders/{folder_id}/path": { "get": { "description": "From the root down; segments the caller may not view have `name: null`.", "operationId": "Folders_path", "parameters": [ { "name": "folder_id", "required": true, "in": "path", "description": "A folder id (ULID), or `root` for the application's root folder.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PathBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Breadcrumbs", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Folders and files", "url": "/concepts/folders-and-files/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/folders/{folder_id}/usage": { "get": { "description": "Computed from the tree, cached for five minutes.", "operationId": "Folders_usage", "parameters": [ { "name": "folder_id", "required": true, "in": "path", "description": "A folder id (ULID), or `root` for the application's root folder.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderUsageBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Bytes, files and folders below", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Folders and files", "url": "/concepts/folders-and-files/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/folders/{folder_id}/copy": { "post": { "description": "The new folder exists at once; a job copies what the caller may view (new ids, no entries, the caller owns the copies).", "operationId": "Folders_copy", "parameters": [ { "name": "folder_id", "required": true, "in": "path", "description": "A folder id (ULID), or `root` for the application's root folder.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Replays the first answer for 24 hours when the same key is sent again (1 to 200 characters).", "required": false, "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyFolderBody" } } } }, "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyFolderResultBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_move`, `depth_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_move", "message": "A folder was moved into itself or one of its own descendants, or the root folder was moved or renamed.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `folder_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `name_conflict`, `folder_busy`, `file_trashed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "name_conflict", "message": "A sibling with the same name exists in the folder (names are compared case-insensitively).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Copy a subtree", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_move", "depth_exceeded", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "folder_managed", "application_not_found", "not_found", "folder_not_found", "name_conflict", "folder_busy", "file_trashed", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Folders and files", "url": "/concepts/folders-and-files/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/folders/{folder_id}/restore": { "post": { "description": "Into its original parent, or the root when that one is gone.", "operationId": "Folders_restore", "parameters": [ { "name": "folder_id", "required": true, "in": "path", "description": "A folder id (ULID), or `root` for the application's root folder.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRefBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Restore a folder from the trash", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "delete", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "folder_managed", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Folders and files", "url": "/concepts/folders-and-files/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/folders/{folder_id}/release-management": { "post": { "description": "The tenant owner's emergency action: removes the application-managed mark from the folder that carries it, so people can change it again. The reason is kept in the audit log (`folder.management_released`). It may break the application's references to the files. Machine clients unmark with `PATCH { managed: false }` instead.", "operationId": "Folders_releaseManagement", "parameters": [ { "name": "folder_id", "required": true, "in": "path", "description": "A folder id (ULID), or `root` for the application's root folder.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseManagementBody" }, "example": { "reason": "The Fitness backend was retired; the files are handed over to the editors" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderBody" }, "example": { "type": "folder", "folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "tenant_id": "fitness-co", "application_id": "fitness-app", "parent_id": "root", "name": "posts", "path": "/posts", "depth": 1, "description": null, "owner_id": "u-ana", "inherit": true, "acl_scope_id": "root", "entries_count": 0, "state": "available", "revision": 1, "metadata": {}, "managed": true, "managed_by": { "client_id": "fitness-backend", "name": "Fitness", "managed_folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "managed_at": "2026-10-22T09:12:33.120Z" }, "created_at": "2026-10-22T09:12:33.120Z", "updated_at": "2026-10-22T09:12:33.120Z", "trashed_at": null, "trashed_by": null, "my_actions": [ "view", "download", "edit", "share", "delete" ] } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `principal_not_allowed`, `files_access_not_granted`, `missing_action`, `tenant_owner_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `folder_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Release a folder from its application's management", "tags": [ "Folders" ], "x-audience": [ "user" ], "x-required-scopes": { "user": [ "files:access" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "principal_not_allowed", "files_access_not_granted", "missing_action", "tenant_owner_required", "application_not_found", "not_found", "folder_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Application-managed folders", "url": "/concepts/managed-folders/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/folders/{folder_id}/permissions": { "get": { "description": "Own and inherited entries and the effective result; everything with `share`, otherwise only the caller's own.", "operationId": "Folders_permissions", "parameters": [ { "name": "folder_id", "required": true, "in": "path", "description": "A folder id (ULID), or `root` for the application's root folder.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPermissionsBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The folder's access entries", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions", "url": "/concepts/permissions/" } }, "put": { "description": "Breaking inheritance copies the effective entries (`copy_inherited`, default); restoring clears the own entries unless `keep_own`.", "operationId": "Folders_replacePermissions", "parameters": [ { "name": "folder_id", "required": true, "in": "path", "description": "A folder id (ULID), or `root` for the application's root folder.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplacePermissionsBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPermissionsBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `cannot_grant_more_than_held`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `too_many_entries`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "too_many_entries", "message": "An item may carry at most 200 access entries of its own.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Replace the folder's entries or change inheritance", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "share", "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "cannot_grant_more_than_held", "folder_managed", "application_not_found", "not_found", "too_many_entries", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions", "url": "/concepts/permissions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/folders/{folder_id}/permissions/entries": { "post": { "description": "A `share` holder grants a subset of their own actions; files.manage grants anything. Inherited by the subtree.", "operationId": "Folders_grant", "parameters": [ { "name": "folder_id", "required": true, "in": "path", "description": "A folder id (ULID), or `root` for the application's root folder.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantEntryBody" }, "example": { "principal": { "type": "role", "role_id": "r-librarian" }, "actions": [ "view", "download", "edit" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessEntryBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `cannot_grant_more_than_held`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `too_many_entries`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "too_many_entries", "message": "An item may carry at most 200 access entries of its own.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Grant an entry", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "share", "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "cannot_grant_more_than_held", "folder_managed", "application_not_found", "not_found", "too_many_entries", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions", "url": "/concepts/permissions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/folders/{folder_id}/permissions/entries/{entry_id}": { "delete": { "operationId": "Folders_revoke", "parameters": [ { "name": "folder_id", "required": true, "in": "path", "description": "A folder id (ULID), or `root` for the application's root folder.", "schema": { "type": "string" } }, { "name": "entry_id", "required": true, "in": "path", "description": "An access entry id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content." }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `cannot_grant_more_than_held`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `entry_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Revoke an entry", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "share", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "cannot_grant_more_than_held", "folder_managed", "application_not_found", "not_found", "entry_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions", "url": "/concepts/permissions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/folders/{folder_id}/shares": { "post": { "description": "The token is shown once. The link grants its actions on the subtree as it is when accessed.", "operationId": "Folders_createShare", "parameters": [ { "name": "folder_id", "required": true, "in": "path", "description": "A folder id (ULID), or `root` for the application's root folder.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Replays the first answer for 24 hours when the same key is sent again (1 to 200 characters).", "required": false, "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShareBody" }, "example": { "actions": [ "view", "download" ], "expires_at": "2026-10-29T09:12:33.120Z", "max_downloads": 10, "label": "For the printer" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedShareBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `share_links_disabled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "share_links_disabled", "message": "Share links are switched off for the application or the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a share link for the folder", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "share", "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "folder_managed", "application_not_found", "not_found", "share_links_disabled", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Share links", "url": "/concepts/shares/" } }, "get": { "description": "Everything with `share`; otherwise the caller's own links.", "operationId": "Folders_listShares", "parameters": [ { "name": "folder_id", "required": true, "in": "path", "description": "A folder id (ULID), or `root` for the application's root folder.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareListBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The folder's share links", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Share links", "url": "/concepts/shares/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/folders/{folder_id}/audit": { "get": { "description": "`view` plus files.audit.read, or files.manage.", "operationId": "Folders_auditTrail", "parameters": [ { "name": "folder_id", "required": true, "in": "path", "description": "A folder id (ULID), or `root` for the application's root folder.", "schema": { "type": "string" } }, { "name": "after", "required": false, "in": "query", "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditPageBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The folder's audit trail", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "missing_capability", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Audit actions", "url": "/reference/audit-actions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/uploads": { "post": { "description": "Checks the name, the declared type and size against the application's policy and the quota, reserves the size, and answers the signed URL (`put`, up to 64 MiB) or the first 100 part URLs (`multipart`). `file_id` is known at once. Needs `edit` on the folder.", "operationId": "Uploads_create", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Replays the first answer for 24 hours when the same key is sent again (1 to 200 characters).", "required": false, "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadBody" }, "example": { "name": "IMG_5913.jpg", "size": 4194304, "mime_type": "image/jpeg", "folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "owner_id": "u-ana", "tags": [ "beach" ], "custom": { "post_id": "123" }, "visibility": "application", "external_ref": "post:123" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadTicketBody" }, "example": { "upload_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4E", "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "version_no": 1, "status": "open", "policy_applied": "default", "method": "put", "url": "https://upload.files.example/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D?signature=...", "headers": { "Content-Type": "image/jpeg" }, "part_size": null, "parts_total": null, "parts": null, "expires_at": "2026-10-22T10:12:33.120Z" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`, `invalid_name`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `tenant_suspended`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `folder_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `name_conflict`, `folder_busy`, `file_trashed`, `idempotency_key_reused`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "name_conflict", "message": "A sibling with the same name exists in the folder (names are compared case-insensitively).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "413": { "description": "Error. `error` is one of: `file_too_large`, `quota_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 413, "error": "file_too_large", "message": "The declared size is above the application's `max_file_size_bytes`, the upload policy's, the tenant's or the platform cap.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `type_not_allowed`, `taxonomy_value_invalid`, `public_visibility_disabled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "type_not_allowed", "message": "The declared or detected type is outside the application's `allowed_types` (or the upload policy's).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`, `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create an upload ticket", "tags": [ "Uploads" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "edit", "x-error-codes": [ "invalid_request", "invalid_name", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "tenant_suspended", "folder_managed", "application_not_found", "not_found", "folder_not_found", "name_conflict", "folder_busy", "file_trashed", "idempotency_key_reused", "file_too_large", "quota_exceeded", "type_not_allowed", "taxonomy_value_invalid", "public_visibility_disabled", "rate_limited", "identity_unavailable", "storage_unavailable" ], "externalDocs": { "description": "Uploads", "url": "/concepts/uploads/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/uploads/{upload_id}": { "get": { "description": "For resuming: continue from the first missing part. The ticket's creator, or the owner of the file it creates.", "operationId": "Uploads_status", "parameters": [ { "name": "upload_id", "required": true, "in": "path", "description": "An upload ticket id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadTicketBody" }, "example": { "upload_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4E", "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "version_no": 1, "status": "open", "policy_applied": "default", "method": "put", "url": "https://upload.files.example/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D?signature=...", "headers": { "Content-Type": "image/jpeg" }, "part_size": null, "parts_total": null, "parts": null, "expires_at": "2026-10-22T10:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `upload_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`, `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "A ticket and the parts the store holds", "tags": [ "Uploads" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-membership-only": true, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "application_not_found", "not_found", "upload_not_found", "rate_limited", "identity_unavailable", "storage_unavailable" ], "externalDocs": { "description": "Uploads", "url": "/concepts/uploads/" } }, "delete": { "description": "Releases the reservation and the stored parts. The creator, or files.manage.", "operationId": "Uploads_abort", "parameters": [ { "name": "upload_id", "required": true, "in": "path", "description": "An upload ticket id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content." }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `upload_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `upload_not_open`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "upload_not_open", "message": "The ticket is already completed, being completed, or aborted.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Abort a ticket", "tags": [ "Uploads" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-membership-only": true, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "application_not_found", "not_found", "upload_not_found", "upload_not_open", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Uploads", "url": "/concepts/uploads/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/uploads/{upload_id}/parts": { "post": { "description": "Each valid one hour; ask again for expired ones.", "operationId": "Uploads_parts", "parameters": [ { "name": "upload_id", "required": true, "in": "path", "description": "An upload ticket id (ULID).", "schema": { "type": "string" } }, { "name": "from", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "count", "required": false, "in": "query", "description": "At most 100.", "schema": { "type": "number" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartUrlsBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `upload_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `upload_not_open`, `upload_expired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "upload_not_open", "message": "The ticket is already completed, being completed, or aborted.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "More part URLs", "tags": [ "Uploads" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-membership-only": true, "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "application_not_found", "not_found", "upload_not_found", "upload_not_open", "upload_expired", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Uploads", "url": "/concepts/uploads/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/uploads/{upload_id}/complete": { "post": { "description": "The service completes the multipart, checks the stored size (a mismatch deletes the object), makes the file available and starts processing. 200 with the file; 202 when a completion above 1,000 parts runs as a job. The creator or the file's owner.", "operationId": "Uploads_complete", "parameters": [ { "name": "upload_id", "required": true, "in": "path", "description": "An upload ticket id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteUploadBody" }, "example": { "parts": [ { "part_number": 1, "etag": "\"a54357aff0632cce46d942af68356b38\"" } ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileBody" }, "example": { "type": "file", "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "tenant_id": "fitness-co", "application_id": "fitness-app", "folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "path": "/posts/IMG_5913.jpg", "name": "IMG_5913.jpg", "extension": "jpg", "mime_type": "image/jpeg", "kind": "image", "size": 4194304, "content_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "title": "Beach", "description": null, "category": "photo", "department": null, "tags": [ "beach" ], "custom": { "post_id": "123" }, "external_ref": "post:123", "owner_id": "u-ana", "created_by": { "user_id": "u-ana", "client_id": "fitness-backend" }, "created_at": "2026-10-22T09:12:33.120Z", "updated_at": "2026-10-22T09:12:33.120Z", "state": "available", "status": "draft", "visibility": "application", "public_url": null, "current_version_no": 1, "versions_count": 1, "revision": 3, "media": { "width": 4032, "height": 3024 }, "processing": { "sniff": "done", "policy": "done", "hash": "done", "scan": "skipped", "metadata": "done", "sanitize": "done", "renditions": "done", "text": "skipped", "publish": "skipped", "notify": "done" }, "renditions": { "thumbnail": { "status": "ready", "mime_type": "image/webp", "size": 8123, "width": 256, "height": 192 }, "preview": { "status": "ready", "mime_type": "image/webp", "size": 98123, "width": 1280, "height": 960 } }, "public_renditions": null, "duplicate_of": null, "lock": null, "editable": false, "hold": null, "managed": true, "managed_by": { "client_id": "fitness-backend", "name": "Fitness", "managed_folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "managed_at": "2026-10-22T09:12:33.120Z" }, "inherit": true, "acl_scope_id": "root", "entries_count": 0, "trashed_at": null, "trashed_by": null, "my_actions": [ "view", "download", "edit", "share", "delete" ] } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `upload_not_found`, `file_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `upload_not_open`, `upload_expired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "upload_not_open", "message": "The ticket is already completed, being completed, or aborted.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `upload_incomplete`, `size_mismatch`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "upload_incomplete", "message": "A multipart completion did not list every part, or a part is missing in the store.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`, `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Complete an upload", "tags": [ "Uploads" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-membership-only": true, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "folder_managed", "application_not_found", "not_found", "upload_not_found", "file_not_found", "upload_not_open", "upload_expired", "upload_incomplete", "size_mismatch", "rate_limited", "identity_unavailable", "storage_unavailable" ], "externalDocs": { "description": "Uploads", "url": "/concepts/uploads/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/urls": { "post": { "description": "Up to 200 ids, one entry per id in order: a feed page in one call. Per-item errors never fail the batch.", "operationId": "Files_urls", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlsRequestBody" }, "example": { "file_ids": [ "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D" ], "rendition": "thumbnail" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlsBody" }, "example": { "items": [ { "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "url": "https://cdn.files.example/...", "expires_at": "2026-10-22T09:27:33.120Z" }, { "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4F", "error": "missing_action" } ] } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `too_many_file_ids`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "too_many_file_ids", "message": "More than 200 ids were sent in one batch.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Mint URLs for many files", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "too_many_file_ids", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Feeds and batch URL minting", "url": "/guides/backend/feeds-and-urls/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/effective-permissions": { "post": { "description": "For a backend deciding for one of its users before it acts. Up to 200 ids.", "operationId": "Files_effectiveBatch", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectivePermissionsRequestBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectivePermissionsBatchBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `principal_not_allowed`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "tenant_not_available", "message": "The tenant in the URL is unknown, suspended or deleted at the Identity Server.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `too_many_file_ids`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "too_many_file_ids", "message": "More than 200 ids were sent in one batch.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "What a user may do with many files", "tags": [ "Files", "Files" ], "x-audience": [ "machine" ], "x-required-scopes": { "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_request", "invalid_token", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "principal_not_allowed", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "too_many_file_ids", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions from code", "url": "/guides/backend/permissions-from-code/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/by-external-ref/{external_ref}": { "get": { "description": "The files carrying `external_ref` (for example `post:123`) that the caller may view.", "operationId": "Files_byExternalRef", "parameters": [ { "name": "external_ref", "required": true, "in": "path", "description": "The tenant's own reference, as set on the file (at most 200 characters).", "schema": { "type": "string" } }, { "name": "after", "required": false, "in": "query", "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilePageBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Files by your reference", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Folders and files", "url": "/concepts/folders-and-files/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}": { "get": { "operationId": "Files_get", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "include", "required": false, "in": "query", "description": "Comma list of `entries`, `versions`, `shares`.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileBody" }, "example": { "type": "file", "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "tenant_id": "fitness-co", "application_id": "fitness-app", "folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "path": "/posts/IMG_5913.jpg", "name": "IMG_5913.jpg", "extension": "jpg", "mime_type": "image/jpeg", "kind": "image", "size": 4194304, "content_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "title": "Beach", "description": null, "category": "photo", "department": null, "tags": [ "beach" ], "custom": { "post_id": "123" }, "external_ref": "post:123", "owner_id": "u-ana", "created_by": { "user_id": "u-ana", "client_id": "fitness-backend" }, "created_at": "2026-10-22T09:12:33.120Z", "updated_at": "2026-10-22T09:12:33.120Z", "state": "available", "status": "draft", "visibility": "application", "public_url": null, "current_version_no": 1, "versions_count": 1, "revision": 3, "media": { "width": 4032, "height": 3024 }, "processing": { "sniff": "done", "policy": "done", "hash": "done", "scan": "skipped", "metadata": "done", "sanitize": "done", "renditions": "done", "text": "skipped", "publish": "skipped", "notify": "done" }, "renditions": { "thumbnail": { "status": "ready", "mime_type": "image/webp", "size": 8123, "width": 256, "height": 192 }, "preview": { "status": "ready", "mime_type": "image/webp", "size": 98123, "width": 1280, "height": 960 } }, "public_renditions": null, "duplicate_of": null, "lock": null, "editable": false, "hold": null, "managed": true, "managed_by": { "client_id": "fitness-backend", "name": "Fitness", "managed_folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "managed_at": "2026-10-22T09:12:33.120Z" }, "inherit": true, "acl_scope_id": "root", "entries_count": 0, "trashed_at": null, "trashed_by": null, "my_actions": [ "view", "download", "edit", "share", "delete" ] } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `file_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "A file", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "file_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Folders and files", "url": "/concepts/folders-and-files/" } }, "patch": { "description": "Metadata, names and moves need `edit` (a move also on the target); status transitions `edit` or `approve`; visibility `share`; owner_id files.manage. A file in review or approved refuses edits from non-approvers.", "operationId": "Files_update", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "if-match", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "description": "The `revision` you read; a stale one answers 412 `revision_mismatch`.", "required": false, "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFileBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileBody" }, "example": { "type": "file", "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "tenant_id": "fitness-co", "application_id": "fitness-app", "folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "path": "/posts/IMG_5913.jpg", "name": "IMG_5913.jpg", "extension": "jpg", "mime_type": "image/jpeg", "kind": "image", "size": 4194304, "content_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "title": "Beach", "description": null, "category": "photo", "department": null, "tags": [ "beach" ], "custom": { "post_id": "123" }, "external_ref": "post:123", "owner_id": "u-ana", "created_by": { "user_id": "u-ana", "client_id": "fitness-backend" }, "created_at": "2026-10-22T09:12:33.120Z", "updated_at": "2026-10-22T09:12:33.120Z", "state": "available", "status": "draft", "visibility": "application", "public_url": null, "current_version_no": 1, "versions_count": 1, "revision": 3, "media": { "width": 4032, "height": 3024 }, "processing": { "sniff": "done", "policy": "done", "hash": "done", "scan": "skipped", "metadata": "done", "sanitize": "done", "renditions": "done", "text": "skipped", "publish": "skipped", "notify": "done" }, "renditions": { "thumbnail": { "status": "ready", "mime_type": "image/webp", "size": 8123, "width": 256, "height": 192 }, "preview": { "status": "ready", "mime_type": "image/webp", "size": 98123, "width": 1280, "height": 960 } }, "public_renditions": null, "duplicate_of": null, "lock": null, "editable": false, "hold": null, "managed": true, "managed_by": { "client_id": "fitness-backend", "name": "Fitness", "managed_folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "managed_at": "2026-10-22T09:12:33.120Z" }, "inherit": true, "acl_scope_id": "root", "entries_count": 0, "trashed_at": null, "trashed_by": null, "my_actions": [ "view", "download", "edit", "share", "delete" ] } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`, `invalid_name`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `file_not_found`, `folder_not_found`, `version_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `name_conflict`, `file_locked`, `status_locked`, `file_trashed`, `file_quarantined`, `folder_busy`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "name_conflict", "message": "A sibling with the same name exists in the folder (names are compared case-insensitively).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "412": { "description": "Error. `error` is one of: `revision_mismatch`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 412, "error": "revision_mismatch", "message": "The `If-Match` revision is stale: the item changed since it was read.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `taxonomy_value_invalid`, `public_visibility_disabled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "taxonomy_value_invalid", "message": "The application enforces its category or department list, and the value is not an active entry of it.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Change metadata, status, visibility, folder or owner", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "edit", "x-error-codes": [ "invalid_request", "invalid_name", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "folder_managed", "application_not_found", "not_found", "file_not_found", "folder_not_found", "version_not_found", "name_conflict", "file_locked", "status_locked", "file_trashed", "file_quarantined", "folder_busy", "revision_mismatch", "taxonomy_value_invalid", "public_visibility_disabled", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Folders and files", "url": "/concepts/folders-and-files/" } }, "delete": { "description": "Restorable within the application's trash retention.", "operationId": "Files_remove", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content." }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `file_trashed`, `file_pending`, `file_locked`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "file_trashed", "message": "The file or folder is in the trash.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Move a file to the trash", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "delete", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "folder_managed", "application_not_found", "not_found", "file_trashed", "file_pending", "file_locked", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Quota and retention", "url": "/concepts/quota-and-retention/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/copy": { "post": { "description": "The current version, under a new id; entries are not copied; the caller owns the copy. `view` on the source, `edit` on the target.", "operationId": "Files_copy", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Replays the first answer for 24 hours when the same key is sent again (1 to 200 characters).", "required": false, "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyFileBody" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileBody" }, "example": { "type": "file", "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "tenant_id": "fitness-co", "application_id": "fitness-app", "folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "path": "/posts/IMG_5913.jpg", "name": "IMG_5913.jpg", "extension": "jpg", "mime_type": "image/jpeg", "kind": "image", "size": 4194304, "content_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "title": "Beach", "description": null, "category": "photo", "department": null, "tags": [ "beach" ], "custom": { "post_id": "123" }, "external_ref": "post:123", "owner_id": "u-ana", "created_by": { "user_id": "u-ana", "client_id": "fitness-backend" }, "created_at": "2026-10-22T09:12:33.120Z", "updated_at": "2026-10-22T09:12:33.120Z", "state": "available", "status": "draft", "visibility": "application", "public_url": null, "current_version_no": 1, "versions_count": 1, "revision": 3, "media": { "width": 4032, "height": 3024 }, "processing": { "sniff": "done", "policy": "done", "hash": "done", "scan": "skipped", "metadata": "done", "sanitize": "done", "renditions": "done", "text": "skipped", "publish": "skipped", "notify": "done" }, "renditions": { "thumbnail": { "status": "ready", "mime_type": "image/webp", "size": 8123, "width": 256, "height": 192 }, "preview": { "status": "ready", "mime_type": "image/webp", "size": 98123, "width": 1280, "height": 960 } }, "public_renditions": null, "duplicate_of": null, "lock": null, "editable": false, "hold": null, "managed": true, "managed_by": { "client_id": "fitness-backend", "name": "Fitness", "managed_folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "managed_at": "2026-10-22T09:12:33.120Z" }, "inherit": true, "acl_scope_id": "root", "entries_count": 0, "trashed_at": null, "trashed_by": null, "my_actions": [ "view", "download", "edit", "share", "delete" ] } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `name_conflict`, `file_trashed`, `file_quarantined`, `file_pending`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "name_conflict", "message": "A sibling with the same name exists in the folder (names are compared case-insensitively).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "413": { "description": "Error. `error` is one of: `quota_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 413, "error": "quota_exceeded", "message": "The upload would exceed the application's or the tenant's quota; the body carries `quota_bytes`, `used_bytes`, `reserved_bytes`.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Copy a file", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "folder_managed", "application_not_found", "not_found", "name_conflict", "file_trashed", "file_quarantined", "file_pending", "quota_exceeded", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Folders and files", "url": "/concepts/folders-and-files/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/restore": { "post": { "description": "`folder_id` when the original folder is gone.", "operationId": "Files_restore", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreFileBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileBody" }, "example": { "type": "file", "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "tenant_id": "fitness-co", "application_id": "fitness-app", "folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "path": "/posts/IMG_5913.jpg", "name": "IMG_5913.jpg", "extension": "jpg", "mime_type": "image/jpeg", "kind": "image", "size": 4194304, "content_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "title": "Beach", "description": null, "category": "photo", "department": null, "tags": [ "beach" ], "custom": { "post_id": "123" }, "external_ref": "post:123", "owner_id": "u-ana", "created_by": { "user_id": "u-ana", "client_id": "fitness-backend" }, "created_at": "2026-10-22T09:12:33.120Z", "updated_at": "2026-10-22T09:12:33.120Z", "state": "available", "status": "draft", "visibility": "application", "public_url": null, "current_version_no": 1, "versions_count": 1, "revision": 3, "media": { "width": 4032, "height": 3024 }, "processing": { "sniff": "done", "policy": "done", "hash": "done", "scan": "skipped", "metadata": "done", "sanitize": "done", "renditions": "done", "text": "skipped", "publish": "skipped", "notify": "done" }, "renditions": { "thumbnail": { "status": "ready", "mime_type": "image/webp", "size": 8123, "width": 256, "height": 192 }, "preview": { "status": "ready", "mime_type": "image/webp", "size": 98123, "width": 1280, "height": 960 } }, "public_renditions": null, "duplicate_of": null, "lock": null, "editable": false, "hold": null, "managed": true, "managed_by": { "client_id": "fitness-backend", "name": "Fitness", "managed_folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "managed_at": "2026-10-22T09:12:33.120Z" }, "inherit": true, "acl_scope_id": "root", "entries_count": 0, "trashed_at": null, "trashed_by": null, "my_actions": [ "view", "download", "edit", "share", "delete" ] } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `file_trashed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "file_trashed", "message": "The file or folder is in the trash.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Restore a file from the trash", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "delete", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "folder_managed", "application_not_found", "not_found", "file_trashed", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Quota and retention", "url": "/concepts/quota-and-retention/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/purge": { "post": { "description": "`delete` and files.manage, or the owner when the application allows it. Irreversible.", "operationId": "Files_purge", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content." }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `missing_capability`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `file_pending`, `file_locked`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "file_pending", "message": "The file's upload has not been completed yet.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Delete a file for good", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "delete", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "missing_capability", "folder_managed", "application_not_found", "not_found", "file_pending", "file_locked", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Quota and retention", "url": "/concepts/quota-and-retention/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/download": { "get": { "description": "`download` for the original as an attachment (audited once per mint); `view` for renditions and inline images, video, audio and PDF.", "operationId": "Files_download", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "disposition", "required": false, "in": "query", "schema": { "enum": [ "attachment", "inline" ], "type": "string" } }, { "name": "version", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "rendition", "required": false, "in": "query", "schema": { "enum": [ "thumbnail", "preview", "large", "poster", "pdf", "mp4_720p", "mp4_1080p", "hls" ], "type": "string" } }, { "name": "ttl_seconds", "required": false, "in": "query", "description": "Machine tokens, up to 86,400.", "schema": { "type": "number" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadBody" }, "example": { "url": "https://cdn.files.example/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D?signature=...", "expires_at": "2026-10-22T09:27:33.120Z", "mime_type": "image/jpeg", "size": 4194304, "name": "IMG_5913.jpg", "version_no": 1 } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `file_not_found`, `version_not_found`, `rendition_not_available`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `scan_pending`, `file_quarantined`, `file_trashed`, `file_pending`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "scan_pending", "message": "The application blocks downloads until the malware scan is clean, and the scan has not finished.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "A signed download URL", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "download", "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "file_not_found", "version_not_found", "rendition_not_available", "scan_pending", "file_quarantined", "file_trashed", "file_pending", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Delivery and visibility", "url": "/concepts/delivery-and-visibility/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/content": { "get": { "description": "The same as download, answered with 302 for clients that follow redirects.", "operationId": "Files_content", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "disposition", "required": false, "in": "query", "schema": { "enum": [ "attachment", "inline" ], "type": "string" } }, { "name": "version", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "rendition", "required": false, "in": "query", "schema": { "enum": [ "thumbnail", "preview", "large", "poster", "pdf", "mp4_720p", "mp4_1080p", "hls" ], "type": "string" } }, { "name": "ttl_seconds", "required": false, "in": "query", "description": "Machine tokens, up to 86,400.", "schema": { "type": "number" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Found: `Location` is the signed URL." }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `file_not_found`, `version_not_found`, `rendition_not_available`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `scan_pending`, `file_quarantined`, `file_trashed`, `file_pending`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "scan_pending", "message": "The application blocks downloads until the malware scan is clean, and the scan has not finished.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Redirect to the signed URL", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "download", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "file_not_found", "version_not_found", "rendition_not_available", "scan_pending", "file_quarantined", "file_trashed", "file_pending", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Delivery and visibility", "url": "/concepts/delivery-and-visibility/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/preview": { "get": { "description": "`kind` picks the component; `url` is the best rendition for it. `kind: none` with `url: null` when nothing can be shown.", "operationId": "Files_preview", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "version", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `file_not_found`, `version_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `scan_pending`, `file_trashed`, `file_quarantined`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "scan_pending", "message": "The application blocks downloads until the malware scan is clean, and the scan has not finished.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "What a viewer needs", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "file_not_found", "version_not_found", "scan_pending", "file_trashed", "file_quarantined", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Previews and renditions", "url": "/concepts/previews-and-renditions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/versions": { "get": { "description": "Newest first.", "operationId": "Files_versions", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "after", "required": false, "in": "query", "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionPageBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The file's versions", "tags": [ "Files", "Versions" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Versions", "url": "/concepts/versions/" } }, "post": { "description": "The same protocol as a new file; completion makes the version current and reopens an approved file as draft.", "operationId": "Files_createVersion", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "if-match", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "description": "The `revision` you read; a stale one answers 412 `revision_mismatch`.", "required": false, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Replays the first answer for 24 hours when the same key is sent again (1 to 200 characters).", "required": false, "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVersionBody" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadTicketBody" }, "example": { "upload_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4E", "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "version_no": 1, "status": "open", "policy_applied": "default", "method": "put", "url": "https://upload.files.example/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D?signature=...", "headers": { "Content-Type": "image/jpeg" }, "part_size": null, "parts_total": null, "parts": null, "expires_at": "2026-10-22T10:12:33.120Z" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `tenant_suspended`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `file_locked`, `status_locked`, `file_trashed`, `file_quarantined`, `file_pending`, `folder_busy`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "file_locked", "message": "Someone else holds a lock (check-out or edit session) on the file; `lock` describes it.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "412": { "description": "Error. `error` is one of: `revision_mismatch`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 412, "error": "revision_mismatch", "message": "The `If-Match` revision is stale: the item changed since it was read.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "413": { "description": "Error. `error` is one of: `file_too_large`, `quota_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 413, "error": "file_too_large", "message": "The declared size is above the application's `max_file_size_bytes`, the upload policy's, the tenant's or the platform cap.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `type_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "type_not_allowed", "message": "The declared or detected type is outside the application's `allowed_types` (or the upload policy's).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`, `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "A ticket for a new version", "tags": [ "Files", "Versions" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "edit", "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "tenant_suspended", "folder_managed", "application_not_found", "not_found", "file_locked", "status_locked", "file_trashed", "file_quarantined", "file_pending", "folder_busy", "revision_mismatch", "file_too_large", "quota_exceeded", "type_not_allowed", "rate_limited", "identity_unavailable", "storage_unavailable" ], "externalDocs": { "description": "Versions", "url": "/concepts/versions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/versions/{version_no}": { "get": { "operationId": "Files_version", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "version_no", "required": true, "in": "path", "description": "A version number (1, 2, ...).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `version_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "One version", "tags": [ "Files", "Versions" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "version_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Versions", "url": "/concepts/versions/" } }, "patch": { "description": "A pinned version is never pruned.", "operationId": "Files_patchVersion", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "version_no", "required": true, "in": "path", "description": "A version number (1, 2, ...).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchVersionBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `version_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Pin a version or change its comment", "tags": [ "Files", "Versions" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "edit", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "folder_managed", "application_not_found", "not_found", "version_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Versions", "url": "/concepts/versions/" } }, "delete": { "description": "Never the current one.", "operationId": "Files_deleteVersion", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "version_no", "required": true, "in": "path", "description": "A version number (1, 2, ...).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content." }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `version_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `version_is_current`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "version_is_current", "message": "The current version cannot be deleted.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Delete a version", "tags": [ "Files", "Versions" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "delete", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "folder_managed", "application_not_found", "not_found", "version_not_found", "version_is_current", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Versions", "url": "/concepts/versions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/versions/{version_no}/restore": { "post": { "description": "A new current version copied from the old one.", "operationId": "Files_restoreVersion", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "version_no", "required": true, "in": "path", "description": "A version number (1, 2, ...).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreVersionBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileBody" }, "example": { "type": "file", "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "tenant_id": "fitness-co", "application_id": "fitness-app", "folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "path": "/posts/IMG_5913.jpg", "name": "IMG_5913.jpg", "extension": "jpg", "mime_type": "image/jpeg", "kind": "image", "size": 4194304, "content_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "title": "Beach", "description": null, "category": "photo", "department": null, "tags": [ "beach" ], "custom": { "post_id": "123" }, "external_ref": "post:123", "owner_id": "u-ana", "created_by": { "user_id": "u-ana", "client_id": "fitness-backend" }, "created_at": "2026-10-22T09:12:33.120Z", "updated_at": "2026-10-22T09:12:33.120Z", "state": "available", "status": "draft", "visibility": "application", "public_url": null, "current_version_no": 1, "versions_count": 1, "revision": 3, "media": { "width": 4032, "height": 3024 }, "processing": { "sniff": "done", "policy": "done", "hash": "done", "scan": "skipped", "metadata": "done", "sanitize": "done", "renditions": "done", "text": "skipped", "publish": "skipped", "notify": "done" }, "renditions": { "thumbnail": { "status": "ready", "mime_type": "image/webp", "size": 8123, "width": 256, "height": 192 }, "preview": { "status": "ready", "mime_type": "image/webp", "size": 98123, "width": 1280, "height": 960 } }, "public_renditions": null, "duplicate_of": null, "lock": null, "editable": false, "hold": null, "managed": true, "managed_by": { "client_id": "fitness-backend", "name": "Fitness", "managed_folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "managed_at": "2026-10-22T09:12:33.120Z" }, "inherit": true, "acl_scope_id": "root", "entries_count": 0, "trashed_at": null, "trashed_by": null, "my_actions": [ "view", "download", "edit", "share", "delete" ] } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `version_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `file_locked`, `status_locked`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "file_locked", "message": "Someone else holds a lock (check-out or edit session) on the file; `lock` describes it.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "413": { "description": "Error. `error` is one of: `quota_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 413, "error": "quota_exceeded", "message": "The upload would exceed the application's or the tenant's quota; the body carries `quota_bytes`, `used_bytes`, `reserved_bytes`.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Restore an old version", "tags": [ "Files", "Versions" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "edit", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "folder_managed", "application_not_found", "not_found", "version_not_found", "file_locked", "status_locked", "quota_exceeded", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Versions", "url": "/concepts/versions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/renditions": { "get": { "operationId": "Files_renditions", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenditionListBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The current version's renditions", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Previews and renditions", "url": "/concepts/previews-and-renditions/" } }, "post": { "operationId": "Files_regenerate", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegenerateRenditionsBody" } } } }, "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRefBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Produce the renditions again", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "edit", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Previews and renditions", "url": "/concepts/previews-and-renditions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/effective-permissions": { "get": { "description": "For a backend deciding for one of its users; `via` lists where each grant comes from.", "operationId": "Files_effective", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "user_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectivePermissionsBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `principal_not_allowed`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "tenant_not_available", "message": "The tenant in the URL is unknown, suspended or deleted at the Identity Server.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "What a user may do with the file", "tags": [ "Files", "Files" ], "x-audience": [ "machine" ], "x-required-scopes": { "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "principal_not_allowed", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions from code", "url": "/guides/backend/permissions-from-code/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/me/permissions": { "get": { "operationId": "Files_mine", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EffectivePermissionsBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `principal_not_allowed`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "What the caller may do with the file", "tags": [ "Files", "Files" ], "x-audience": [ "user" ], "x-required-scopes": { "user": [ "files:access" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "principal_not_allowed", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions", "url": "/concepts/permissions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/permissions": { "get": { "description": "Own and inherited entries; everything with `share`, otherwise only the caller's own.", "operationId": "Files_permissions", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPermissionsBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The file's access entries", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions", "url": "/concepts/permissions/" } }, "put": { "operationId": "Files_replacePermissions", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplacePermissionsBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPermissionsBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `cannot_grant_more_than_held`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `too_many_entries`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "too_many_entries", "message": "An item may carry at most 200 access entries of its own.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Replace the file's entries or change inheritance", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "share", "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "cannot_grant_more_than_held", "folder_managed", "application_not_found", "not_found", "too_many_entries", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions", "url": "/concepts/permissions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/permissions/entries": { "post": { "operationId": "Files_grant", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantEntryBody" }, "example": { "principal": { "type": "role", "role_id": "r-librarian" }, "actions": [ "view", "download", "edit" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessEntryBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `cannot_grant_more_than_held`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `too_many_entries`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "too_many_entries", "message": "An item may carry at most 200 access entries of its own.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Grant an entry on the file", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "share", "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "cannot_grant_more_than_held", "folder_managed", "application_not_found", "not_found", "too_many_entries", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions", "url": "/concepts/permissions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/permissions/entries/{entry_id}": { "delete": { "operationId": "Files_revoke", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "entry_id", "required": true, "in": "path", "description": "An access entry id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content." }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `cannot_grant_more_than_held`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `entry_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Revoke an entry on the file", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "share", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "cannot_grant_more_than_held", "folder_managed", "application_not_found", "not_found", "entry_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions", "url": "/concepts/permissions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/shares": { "post": { "description": "The token is shown once.", "operationId": "Files_createShare", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Replays the first answer for 24 hours when the same key is sent again (1 to 200 characters).", "required": false, "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShareBody" }, "example": { "actions": [ "view", "download" ], "expires_at": "2026-10-29T09:12:33.120Z", "max_downloads": 10, "label": "For the printer" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedShareBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `folder_managed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `share_links_disabled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "share_links_disabled", "message": "Share links are switched off for the application or the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a share link for the file", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "share", "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "folder_managed", "application_not_found", "not_found", "share_links_disabled", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Share links", "url": "/concepts/shares/" } }, "get": { "operationId": "Files_listShares", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareListBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The file's share links", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Share links", "url": "/concepts/shares/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/audit": { "get": { "description": "`view` plus files.audit.read, or files.manage.", "operationId": "Files_auditTrail", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "after", "required": false, "in": "query", "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditPageBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The file's audit trail", "tags": [ "Files", "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "missing_capability", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Audit actions", "url": "/reference/audit-actions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/checkout": { "post": { "description": "Locks the file for the caller. Answers 501 until editing is served.", "operationId": "Files_checkout", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created." }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "501": { "description": "Error. `error` is one of: `not_implemented`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 501, "error": "not_implemented", "message": "The route is planned (check-out, check-in, edit sessions) and not served yet.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Check out a file (planned)", "tags": [ "Files", "Files" ], "x-status": "planned", "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "edit", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "not_implemented", "identity_unavailable" ], "externalDocs": { "description": "Versions", "url": "/concepts/versions/" } }, "delete": { "description": "The holder; files.manage breaks it with `force: true`. Answers 501 until editing is served.", "operationId": "Files_discardCheckout", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "501": { "description": "Error. `error` is one of: `not_implemented`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 501, "error": "not_implemented", "message": "The route is planned (check-out, check-in, edit sessions) and not served yet.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Discard a check-out (planned)", "tags": [ "Files", "Files" ], "x-status": "planned", "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "edit", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "not_implemented", "identity_unavailable" ], "externalDocs": { "description": "Versions", "url": "/concepts/versions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/checkin": { "post": { "description": "A version ticket whose completion releases the lock. Answers 501 until editing is served.", "operationId": "Files_checkin", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created." }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "501": { "description": "Error. `error` is one of: `not_implemented`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 501, "error": "not_implemented", "message": "The route is planned (check-out, check-in, edit sessions) and not served yet.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Check in a file (planned)", "tags": [ "Files", "Files" ], "x-status": "planned", "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "edit", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "not_implemented", "identity_unavailable" ], "externalDocs": { "description": "Versions", "url": "/concepts/versions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/edit-sessions": { "post": { "description": "Answers 501 until editing is served.", "operationId": "Files_editSession", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created." }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "501": { "description": "Error. `error` is one of: `not_implemented`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 501, "error": "not_implemented", "message": "The route is planned (check-out, check-in, edit sessions) and not served yet.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Open the file in an editor (planned)", "tags": [ "Files", "Files" ], "x-status": "planned", "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-action": "edit", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "not_implemented", "identity_unavailable" ], "externalDocs": { "description": "Versions", "url": "/concepts/versions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/holds": { "get": { "description": "Every held file of the application, in any state (trashed and quarantined included), the newest hold first. files.manage.", "operationId": "Holds_list", "parameters": [ { "name": "after", "required": false, "in": "query", "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "placed_by", "required": false, "in": "query", "description": "Only the holds a user (or a client) placed.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilePageBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_cursor`, `invalid_limit`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_cursor", "message": "The `after` cursor is not one this service issued for this listing.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Files under a legal hold", "tags": [ "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-capabilities": { "all": [ "files.manage" ] }, "x-error-codes": [ "invalid_cursor", "invalid_limit", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_capability", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Legal hold", "url": "/concepts/legal-hold/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/files/{file_id}/hold": { "put": { "description": "Or change the reason and the end of the one in place. While the hold is in force the file cannot be purged (by anyone, nor by the trash's retention or emptying), its versions are neither deleted nor pruned, and a storage migration keeps its source copies; it can still be trashed and restored, edited and given new versions. files.manage. The reason is visible to everyone who can view the file.", "operationId": "Holds_place", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceHoldBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileBody" }, "example": { "type": "file", "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "tenant_id": "fitness-co", "application_id": "fitness-app", "folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "path": "/posts/IMG_5913.jpg", "name": "IMG_5913.jpg", "extension": "jpg", "mime_type": "image/jpeg", "kind": "image", "size": 4194304, "content_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "title": "Beach", "description": null, "category": "photo", "department": null, "tags": [ "beach" ], "custom": { "post_id": "123" }, "external_ref": "post:123", "owner_id": "u-ana", "created_by": { "user_id": "u-ana", "client_id": "fitness-backend" }, "created_at": "2026-10-22T09:12:33.120Z", "updated_at": "2026-10-22T09:12:33.120Z", "state": "available", "status": "draft", "visibility": "application", "public_url": null, "current_version_no": 1, "versions_count": 1, "revision": 3, "media": { "width": 4032, "height": 3024 }, "processing": { "sniff": "done", "policy": "done", "hash": "done", "scan": "skipped", "metadata": "done", "sanitize": "done", "renditions": "done", "text": "skipped", "publish": "skipped", "notify": "done" }, "renditions": { "thumbnail": { "status": "ready", "mime_type": "image/webp", "size": 8123, "width": 256, "height": 192 }, "preview": { "status": "ready", "mime_type": "image/webp", "size": 98123, "width": 1280, "height": 960 } }, "public_renditions": null, "duplicate_of": null, "lock": null, "editable": false, "hold": null, "managed": true, "managed_by": { "client_id": "fitness-backend", "name": "Fitness", "managed_folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "managed_at": "2026-10-22T09:12:33.120Z" }, "inherit": true, "acl_scope_id": "root", "entries_count": 0, "trashed_at": null, "trashed_by": null, "my_actions": [ "view", "download", "edit", "share", "delete" ] } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `file_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `file_pending`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "file_pending", "message": "The file's upload has not been completed yet.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Place a legal hold on a file", "tags": [ "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-capabilities": { "all": [ "files.manage" ] }, "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_capability", "application_not_found", "not_found", "file_not_found", "file_pending", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Legal hold", "url": "/concepts/legal-hold/" } }, "delete": { "description": "An optional reason goes to the audit log. A file without a hold answers unchanged. files.manage.", "operationId": "Holds_release", "parameters": [ { "name": "file_id", "required": true, "in": "path", "description": "A file id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseHoldBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileBody" }, "example": { "type": "file", "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "tenant_id": "fitness-co", "application_id": "fitness-app", "folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "path": "/posts/IMG_5913.jpg", "name": "IMG_5913.jpg", "extension": "jpg", "mime_type": "image/jpeg", "kind": "image", "size": 4194304, "content_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "title": "Beach", "description": null, "category": "photo", "department": null, "tags": [ "beach" ], "custom": { "post_id": "123" }, "external_ref": "post:123", "owner_id": "u-ana", "created_by": { "user_id": "u-ana", "client_id": "fitness-backend" }, "created_at": "2026-10-22T09:12:33.120Z", "updated_at": "2026-10-22T09:12:33.120Z", "state": "available", "status": "draft", "visibility": "application", "public_url": null, "current_version_no": 1, "versions_count": 1, "revision": 3, "media": { "width": 4032, "height": 3024 }, "processing": { "sniff": "done", "policy": "done", "hash": "done", "scan": "skipped", "metadata": "done", "sanitize": "done", "renditions": "done", "text": "skipped", "publish": "skipped", "notify": "done" }, "renditions": { "thumbnail": { "status": "ready", "mime_type": "image/webp", "size": 8123, "width": 256, "height": 192 }, "preview": { "status": "ready", "mime_type": "image/webp", "size": 98123, "width": 1280, "height": 960 } }, "public_renditions": null, "duplicate_of": null, "lock": null, "editable": false, "hold": null, "managed": true, "managed_by": { "client_id": "fitness-backend", "name": "Fitness", "managed_folder_id": "01J9Z6R2M3N4P5Q6R7S8T9V0W1", "managed_at": "2026-10-22T09:12:33.120Z" }, "inherit": true, "acl_scope_id": "root", "entries_count": 0, "trashed_at": null, "trashed_by": null, "my_actions": [ "view", "download", "edit", "share", "delete" ] } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `file_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Release the legal hold of a file", "tags": [ "Files" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-capabilities": { "all": [ "files.manage" ] }, "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_capability", "application_not_found", "not_found", "file_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Legal hold", "url": "/concepts/legal-hold/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/search": { "get": { "description": "Names, keywords, document text (`in=content`) and every filter, within what the caller may view (applied inside the query, so paging and totals are exact).", "operationId": "Search_run", "parameters": [ { "name": "custom.", "required": false, "in": "query", "description": "Exact match on a custom metadata value (at most 5 keys).", "schema": { "type": "string" } }, { "name": "q", "required": false, "in": "query", "description": "Words; quoted phrases match as a whole.", "schema": { "type": "string" } }, { "name": "in", "required": false, "in": "query", "description": "Comma list of `name`, `keywords`, `content` (default `name,keywords`). `content` searches the text extracted from documents (PDF, Office, text) and answers a short `content` highlight; never the text itself.", "schema": { "type": "string" } }, { "name": "folder_id", "required": false, "in": "query", "description": "Limit to a folder.", "schema": { "type": "string" } }, { "name": "recursive", "required": false, "in": "query", "description": "With folder_id: the whole subtree.", "schema": { "type": "string" } }, { "name": "kind", "required": false, "in": "query", "description": "Comma list.", "schema": { "type": "string" } }, { "name": "mime_type", "required": false, "in": "query", "description": "Comma list.", "schema": { "type": "string" } }, { "name": "extension", "required": false, "in": "query", "description": "Comma list.", "schema": { "type": "string" } }, { "name": "created_from", "required": false, "in": "query", "description": "ISO date.", "schema": { "type": "string" } }, { "name": "created_to", "required": false, "in": "query", "description": "ISO date.", "schema": { "type": "string" } }, { "name": "updated_from", "required": false, "in": "query", "description": "ISO date.", "schema": { "type": "string" } }, { "name": "updated_to", "required": false, "in": "query", "description": "ISO date.", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Comma list.", "schema": { "type": "string" } }, { "name": "visibility", "required": false, "in": "query", "description": "Comma list.", "schema": { "type": "string" } }, { "name": "state", "required": false, "in": "query", "description": "`available` by default; `trashed` lists what you may restore.", "schema": { "type": "string" } }, { "name": "owner_id", "required": false, "in": "query", "description": "", "schema": { "type": "string" } }, { "name": "created_by_user_id", "required": false, "in": "query", "description": "", "schema": { "type": "string" } }, { "name": "created_by_client_id", "required": false, "in": "query", "description": "", "schema": { "type": "string" } }, { "name": "department", "required": false, "in": "query", "description": "", "schema": { "type": "string" } }, { "name": "category", "required": false, "in": "query", "description": "", "schema": { "type": "string" } }, { "name": "tags", "required": false, "in": "query", "description": "Comma list.", "schema": { "type": "string" } }, { "name": "tags_match", "required": false, "in": "query", "description": "`any` (default) or `all`.", "schema": { "type": "string" } }, { "name": "external_ref", "required": false, "in": "query", "description": "Exact.", "schema": { "type": "string" } }, { "name": "min_size", "required": false, "in": "query", "description": "Bytes.", "schema": { "type": "string" } }, { "name": "max_size", "required": false, "in": "query", "description": "Bytes.", "schema": { "type": "string" } }, { "name": "sort", "required": false, "in": "query", "description": "`relevance` (with q), `name`, `created_at`, `updated_at`, `size`.", "schema": { "type": "string" } }, { "name": "order", "required": false, "in": "query", "description": "`asc` or `desc`.", "schema": { "type": "string" } }, { "name": "after", "required": false, "in": "query", "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "50 by default, at most 200.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResultBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`, `invalid_cursor`, `invalid_limit`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `too_many_scopes`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "too_many_scopes", "message": "The caller's access spans more than 5,000 permission scopes, too many for one search across the application.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Search files", "tags": [ "Search" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_request", "invalid_cursor", "invalid_limit", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "too_many_scopes", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Search", "url": "/concepts/search/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/tags": { "get": { "description": "With how many available files carry each.", "operationId": "Search_tagList", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "prefix", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagListBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Tags in use", "tags": [ "Search" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Search", "url": "/concepts/search/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/taxonomies/{name}": { "get": { "description": "`categories` or `departments`.", "operationId": "Search_taxonomy", "parameters": [ { "name": "name", "required": true, "in": "path", "description": "The managed value list: `categories` or `departments`.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `taxonomy_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "A managed value list", "tags": [ "Search" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "view", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "taxonomy_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Settings reference", "url": "/reference/settings/" } }, "put": { "description": "When `enforced`, uploads and patches must use an active value.", "operationId": "Search_setTaxonomy", "parameters": [ { "name": "name", "required": true, "in": "path", "description": "The managed value list: `categories` or `departments`.", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTaxonomyBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `taxonomy_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Replace a managed value list", "tags": [ "Search" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-required-capabilities": { "all": [ "files.settings.manage" ] }, "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_capability", "application_not_found", "not_found", "taxonomy_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Settings reference", "url": "/reference/settings/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/principals/roles": { "get": { "description": "The tenant's roles and the application's own; never `tenant_owner`.", "operationId": "Principals_roles", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrincipalRoleListBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The roles an entry may name", "tags": [ "Permissions" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-membership-only": true, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions", "url": "/concepts/permissions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/principals/users": { "get": { "description": "Members matching `q`. Needs `share` somewhere in the application, or files.manage.", "operationId": "Principals_users", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "q", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrincipalUserListBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The user picker", "tags": [ "Permissions" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-membership-only": true, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Permissions", "url": "/concepts/permissions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/shares": { "get": { "description": "Every link with files.manage; otherwise the caller's own links.", "operationId": "Shares_list", "parameters": [ { "name": "created_by", "required": false, "in": "query", "description": "A user id.", "schema": { "type": "string" } }, { "name": "after", "required": false, "in": "query", "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareListBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The application's share links", "tags": [ "Shares" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-membership-only": true, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Share links", "url": "/concepts/shares/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/shares/{share_id}": { "delete": { "description": "The creator, a holder of `share` on the target, or files.manage.", "operationId": "Shares_revoke", "parameters": [ { "name": "share_id", "required": true, "in": "path", "description": "A share link id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content." }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `share_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Revoke a share link", "tags": [ "Shares" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-membership-only": true, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "application_not_found", "not_found", "share_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Share links", "url": "/concepts/shares/" } } }, "/api/v1/shares/{token}": { "get": { "description": "The target's public metadata and, for a folder, its listing.", "operationId": "PublicShares_open", "parameters": [ { "name": "token", "required": true, "in": "path", "description": "The share link token.", "schema": { "type": "string" } }, { "name": "folder_id", "required": false, "in": "query", "description": "Folder links: browse a folder within the shared one.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicShareBody" } } } }, "404": { "description": "Error. `error` is one of: `share_not_found`, `folder_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "share_not_found", "message": "No share link with this id or token exists.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "410": { "description": "Error. `error` is one of: `share_gone`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 410, "error": "share_gone", "message": "The share link was revoked or expired, or its target was trashed or quarantined.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "summary": "What a share link shows", "tags": [ "Shares" ], "x-audience": [ "public" ], "x-error-codes": [ "share_not_found", "folder_not_found", "share_gone", "rate_limited" ], "externalDocs": { "description": "Share links", "url": "/concepts/shares/" } } }, "/api/v1/shares/{token}/download": { "post": { "description": "Five minutes; within the link's actions (a view-only link answers inline media only).", "operationId": "PublicShares_download", "parameters": [ { "name": "token", "required": true, "in": "path", "description": "The share link token.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareDownloadRequestBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignedUrlBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `share_password_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "share_password_required", "message": "The share link is protected by a password and none was sent.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `share_password_invalid`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "share_password_invalid", "message": "The password sent for the share link is wrong", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `share_not_found`, `file_not_found`, `rendition_not_available`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "share_not_found", "message": "No share link with this id or token exists.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `scan_pending`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "scan_pending", "message": "The application blocks downloads until the malware scan is clean, and the scan has not finished.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "410": { "description": "Error. `error` is one of: `share_gone`, `share_limit_reached`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 410, "error": "share_gone", "message": "The share link was revoked or expired, or its target was trashed or quarantined.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "summary": "A URL for the shared file", "tags": [ "Shares" ], "x-audience": [ "public" ], "x-error-codes": [ "invalid_request", "share_password_required", "share_password_invalid", "missing_action", "share_not_found", "file_not_found", "rendition_not_available", "scan_pending", "share_gone", "share_limit_reached", "rate_limited" ], "externalDocs": { "description": "Share links", "url": "/concepts/shares/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/trash": { "get": { "description": "What one delete trashed (a file, or a folder with its subtree), newest first, that the caller may restore; everything with files.manage.", "operationId": "Trash_list", "parameters": [ { "name": "after", "required": false, "in": "query", "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "sort", "required": false, "in": "query", "schema": { "enum": [ "trashed_at" ], "type": "string" } }, { "name": "type", "required": false, "in": "query", "schema": { "enum": [ "all", "files", "folders" ], "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrashPageBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "What was deleted", "tags": [ "Trash" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read" ] }, "x-required-action": "delete", "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_action", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Quota and retention", "url": "/concepts/quota-and-retention/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/trash/empty": { "post": { "description": "Purges everything in it. files.manage. Irreversible.", "operationId": "Trash_empty", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobRefBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Empty the trash", "tags": [ "Trash" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage" ] }, "x-required-capabilities": { "all": [ "files.manage" ] }, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_capability", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Quota and retention", "url": "/concepts/quota-and-retention/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/settings/public": { "get": { "description": "The size cap, the allowed types and the named upload policies as enforced (within the tenant's ceilings), for any member.", "operationId": "Settings_publicSettings", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSettingsBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "What an uploader needs first", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read", "files:config.manage" ] }, "x-membership-only": true, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Settings reference", "url": "/reference/settings/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/settings": { "get": { "description": "files.settings.manage, or a machine client with files:config.manage.", "operationId": "Settings_get", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The application's settings", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-required-capabilities": { "all": [ "files.settings.manage" ] }, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_capability", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Settings reference", "url": "/reference/settings/" } }, "put": { "description": "A partial merge, validated against the tenant's ceilings and the platform caps.", "operationId": "Settings_put", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `public_visibility_disabled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "public_visibility_disabled", "message": "`visibility: public` was requested and the application (or the tenant) does not allow public files.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Change settings", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-required-capabilities": { "all": [ "files.settings.manage" ] }, "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_capability", "application_not_found", "not_found", "public_visibility_disabled", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Settings reference", "url": "/reference/settings/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/usage": { "get": { "description": "files.audit.read or files.settings.manage, or any machine client of the context.", "operationId": "Settings_usage", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The application's usage against its quotas", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read", "files:config.manage" ] }, "x-membership-only": true, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_capability", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Quota and retention", "url": "/concepts/quota-and-retention/" } } }, "/api/v1/tenants/{tenant_id}/usage": { "get": { "description": "A user with either administration key in any application of the tenant, or a machine client of the tenant.", "operationId": "TenantUsage_usage", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUsageBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The tenant's usage per application", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read", "files:config.manage" ] }, "x-membership-only": true, "x-error-codes": [ "invalid_token", "not_tenant_member", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_capability", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Quota and retention", "url": "/concepts/quota-and-retention/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/audit": { "get": { "description": "Newest first. files.audit.read.", "operationId": "Audit_list", "parameters": [ { "name": "to", "required": false, "in": "query", "description": "ISO date.", "schema": { "type": "string" } }, { "name": "from", "required": false, "in": "query", "description": "ISO date.", "schema": { "type": "string" } }, { "name": "target_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "target_type", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "actor_client_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "actor_user_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "action", "required": false, "in": "query", "description": "Comma list.", "schema": { "type": "string" } }, { "name": "after", "required": false, "in": "query", "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditPageBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The audit log", "tags": [ "Audit" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-required-capabilities": { "all": [ "files.audit.read" ] }, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_capability", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Audit actions", "url": "/reference/audit-actions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/audit/export": { "get": { "description": "JSON lines, streamed, at most 100,000 rows; the same filters as the list (action, actor_user_id, actor_client_id, target_type, target_id, from, to).", "operationId": "Audit_export", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "One audit row per line.", "content": { "application/x-ndjson": { "schema": { "type": "string" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Export the audit log", "tags": [ "Audit" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-required-capabilities": { "all": [ "files.audit.read" ] }, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_capability", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Audit actions", "url": "/reference/audit-actions/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/jobs/{job_id}": { "get": { "description": "The creator, or files.manage.", "operationId": "Jobs_get", "parameters": [ { "name": "job_id", "required": true, "in": "path", "description": "A job id (ULID).", "schema": { "type": "string" } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`, `job_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "A job", "tags": [ "Folders" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:manage", "files:read", "files:config.manage" ] }, "x-membership-only": true, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "application_not_found", "not_found", "job_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Folders and files", "url": "/concepts/folders-and-files/" } } }, "/api/v1/platform/tenants": { "get": { "operationId": "Platform_tenants", "parameters": [ { "name": "q", "required": false, "in": "query", "description": "Matches the tenant id, name or slug.", "schema": { "type": "string" } }, { "name": "after", "required": false, "in": "query", "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformTenantPageBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "insufficient_scope", "message": "A user token lacks `files:access`, a machine token carries none of `files:manage`, `files:read`, `files:config.manage`, or the route needs a scope the token does not carry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Every tenant with its usage and quota (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_token", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Platform administration", "url": "/administration/platform/" } } }, "/api/v1/platform/tenants/{tenant_id}": { "get": { "operationId": "Platform_tenant", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformTenantDetailBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "One tenant: usage per application and the tenant settings (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_token", "not_tenant_member", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Platform administration", "url": "/administration/platform/" } } }, "/api/v1/platform/tenants/{tenant_id}/settings": { "put": { "description": "A partial merge: quota (`null` = unlimited), max file size, allowed types, public visibility, share links, suspension, a note. Audited with before and after.", "operationId": "Platform_setTenantSettings", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantSettingsBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantSettingsBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Set a tenant's ceilings (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Platform administration", "url": "/administration/platform/" } } }, "/api/v1/platform/settings": { "get": { "operationId": "Platform_defaults", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDefaultsBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "insufficient_scope", "message": "A user token lacks `files:access`, a machine token carries none of `files:manage`, `files:read`, `files:config.manage`, or the route needs a scope the token does not carry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The platform defaults (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_token", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Platform administration", "url": "/administration/platform/" } }, "put": { "description": "They apply to tenants without ceilings of their own.", "operationId": "Platform_setDefaults", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDefaultsBody" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformDefaultsBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "insufficient_scope", "message": "A user token lacks `files:access`, a machine token carries none of `files:manage`, `files:read`, `files:config.manage`, or the route needs a scope the token does not carry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Change the platform defaults (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_request", "invalid_token", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Platform administration", "url": "/administration/platform/" } } }, "/api/v1/platform/usage": { "get": { "description": "Every tenant with usage or history, ranked by `sort` (largest first, nulls last): `used_bytes` (the top tenants), `growth_bytes` (first to last daily snapshot of the window) or `quota_ratio` (used and reserved bytes over the quota: quota pressure). `totals` sums every tenant, with its daily series. From the daily usage snapshots.", "operationId": "PlatformUsage_usage", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "sort", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "used_bytes", "growth_bytes", "quota_ratio" ], "default": "used_bytes" } }, { "name": "days", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformUsageTrendsBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`, `invalid_limit`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "insufficient_scope", "message": "A user token lacks `files:access`, a machine token carries none of `files:manage`, `files:read`, `files:config.manage`, or the route needs a scope the token does not carry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Usage trends across tenants (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_request", "invalid_limit", "invalid_token", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Platform administration", "url": "/administration/platform/" } } }, "/api/v1/platform/tenants/{tenant_id}/usage": { "get": { "description": "The tenant's daily snapshots and each application's, oldest first; days without a snapshot are absent.", "operationId": "PlatformUsage_tenantUsage", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "days", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 400, "default": 30 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformTenantUsageTrendBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "One tenant's usage trend, per application (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Platform administration", "url": "/administration/platform/" } } }, "/api/v1/platform/tenants/{tenant_id}/usage/export": { "get": { "description": "The daily snapshots of a period of at most 400 days: one row per day for the tenant and one per application and day (bytes, renditions, trash, reserved, files, versions, quota, bytes by kind). NDJSON or CSV, streamed. Audited (`usage.exported`).", "operationId": "PlatformUsage_usageExport", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "format", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "ndjson", "csv" ], "default": "ndjson" } }, { "name": "to", "required": false, "in": "query", "description": "Last day, `YYYY-MM-DD` (default: today, UTC).", "schema": { "type": "string" } }, { "name": "from", "required": false, "in": "query", "description": "First day, `YYYY-MM-DD` (default: 29 days before `to`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "One row per line (CSV: a header line first).", "content": { "application/x-ndjson": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } }, "headers": { "X-Export-Truncated": { "description": "`true` when the row cap cut the export, else `false`.", "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Export a tenant's daily usage (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Platform administration", "url": "/administration/platform/" } } }, "/api/v1/platform/tenants/{tenant_id}/audit": { "get": { "description": "Newest first, the filters of `GET P/audit` plus `application_id`. Each read is itself audited (`tenant_audit.read`, on the tenant).", "operationId": "PlatformAudit_list", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "ISO date.", "schema": { "type": "string" } }, { "name": "from", "required": false, "in": "query", "description": "ISO date.", "schema": { "type": "string" } }, { "name": "target_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "target_type", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "actor_client_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "actor_user_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "action", "required": false, "in": "query", "description": "Comma list.", "schema": { "type": "string" } }, { "name": "application_id", "required": false, "in": "query", "description": "One application of the tenant (default: every application and the tenant-level rows).", "schema": { "type": "string" } }, { "name": "after", "required": false, "in": "query", "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditPageBody" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`, `invalid_limit`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "A tenant's audit log across its applications (platform administrators)", "tags": [ "Audit" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_request", "invalid_limit", "invalid_token", "not_tenant_member", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Platform administration", "url": "/administration/platform/" } } }, "/api/v1/platform/tenants/{tenant_id}/audit/export": { "get": { "description": "NDJSON (one audit row per line) or CSV (`metadata` as JSON), streamed, newest first, at most 100,000 rows; `X-Export-Truncated: true` when the filters match more. Audited (`audit.exported`).", "operationId": "PlatformAudit_export", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "format", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "ndjson", "csv" ], "default": "ndjson" } }, { "name": "to", "required": false, "in": "query", "description": "ISO date.", "schema": { "type": "string" } }, { "name": "from", "required": false, "in": "query", "description": "ISO date.", "schema": { "type": "string" } }, { "name": "target_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "target_type", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "actor_client_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "actor_user_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "action", "required": false, "in": "query", "description": "Comma list.", "schema": { "type": "string" } }, { "name": "application_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "One row per line (CSV: a header line first).", "content": { "application/x-ndjson": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } }, "headers": { "X-Export-Truncated": { "description": "`true` when the row cap cut the export, else `false`.", "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Export a tenant's audit log (platform administrators)", "tags": [ "Audit" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Platform administration", "url": "/administration/platform/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/webhooks": { "get": { "description": "The URL, the subscribed events and the state; the secret is write-only and never returned. `url: null` when none is set.", "operationId": "Webhooks_get", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfig" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The application's webhook", "tags": [ "Webhooks" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-required-capabilities": { "all": [ "files.settings.manage" ] }, "x-error-codes": [ "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_capability", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Webhooks", "url": "/guides/backend/webhooks/" } }, "put": { "description": "One webhook per application. An active webhook is first sent a signed `ping` event: unless it answers 2xx within the timeout (5 s by default), nothing is saved and the answer is 422 `webhook_unreachable`. Leave `secret` out to keep the stored one. Audited `webhook.updated` (never the secret).", "operationId": "Webhooks_set", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfig" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`, `webhook_url_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `webhook_unreachable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "webhook_unreachable", "message": "The webhook URL did not answer the verification ping with a 2xx within 5 seconds.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Set the webhook", "tags": [ "Webhooks" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-required-capabilities": { "all": [ "files.settings.manage" ] }, "x-error-codes": [ "invalid_request", "webhook_url_not_allowed", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_capability", "application_not_found", "not_found", "webhook_unreachable", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Webhooks", "url": "/guides/backend/webhooks/" } } }, "/api/v1/tenants/{tenant_id}/applications/{application_id}/webhooks/deliveries": { "get": { "description": "One row per attempt of the last 7 days, newest first: the event, the attempt, the outcome and the response code.", "operationId": "Webhooks_deliveries", "parameters": [ { "name": "after", "required": false, "in": "query", "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "application_id", "required": true, "in": "path", "description": "The Identity Server application id: a tenant application, or (platform clients) the client's own platform application.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryPage" } } } }, "400": { "description": "Error. `error` is one of: `invalid_cursor`, `invalid_limit`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_cursor", "message": "The `after` cursor is not one this service issued for this listing.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `no_application_access`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `missing_capability`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `application_not_found`, `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "application_not_found", "message": "The application in the URL is not an active application of the tenant.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The delivery log", "tags": [ "Webhooks" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-required-capabilities": { "all": [ "files.settings.manage" ] }, "x-error-codes": [ "invalid_cursor", "invalid_limit", "invalid_token", "not_tenant_member", "no_application_access", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "missing_capability", "application_not_found", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Webhooks", "url": "/guides/backend/webhooks/" } } }, "/api/v1/platform/storage-accounts": { "get": { "description": "The platform storage of this environment (`default`) first, then the accounts created here. Credentials are never returned.", "operationId": "StorageAccounts_list", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageAccountPageBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "insufficient_scope", "message": "A user token lacks `files:access`, a machine token carries none of `files:manage`, `files:read`, `files:config.manage`, or the route needs a scope the token does not carry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "The storage accounts (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_token", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Storage accounts", "url": "/administration/storage/" } }, "post": { "description": "A bucket account (bucket, region, endpoint, credentials) or, where the deployment allows it, a directory account (`adapter: filesystem`). The account is saved only after a write, read and delete probe succeeded. Audited.", "operationId": "StorageAccounts_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStorageAccountInput" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageAccountBodyDoc" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "insufficient_scope", "message": "A user token lacks `files:access`, a machine token carries none of `files:manage`, `files:read`, `files:config.manage`, or the route needs a scope the token does not carry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `storage_account_in_use`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "storage_account_in_use", "message": "The storage account still holds objects, is assigned to a tenant or takes part in a migration, so it cannot be removed or have its location changed.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `storage_account_verification_failed`, `storage_adapter_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "storage_account_verification_failed", "message": "The write, read and delete probe against the storage account failed; nothing was saved.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a storage account (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_request", "invalid_token", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "storage_account_in_use", "storage_account_verification_failed", "storage_adapter_not_allowed", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Storage accounts", "url": "/administration/storage/" } } }, "/api/v1/platform/storage-accounts/{storage_account_id}": { "get": { "operationId": "StorageAccounts_get", "parameters": [ { "name": "storage_account_id", "required": true, "in": "path", "description": "A storage account id (ULID), or `default` for the platform storage of this environment.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageAccountBodyDoc" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "insufficient_scope", "message": "A user token lacks `files:access`, a machine token carries none of `files:manage`, `files:read`, `files:config.manage`, or the route needs a scope the token does not carry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`, `storage_account_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "A storage account (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_token", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "not_found", "storage_account_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Storage accounts", "url": "/administration/storage/" } }, "patch": { "description": "Rename it, rotate its credentials, or change its location while nothing uses it. A change of credentials or location is probed before it is saved. Audited.", "operationId": "StorageAccounts_update", "parameters": [ { "name": "storage_account_id", "required": true, "in": "path", "description": "A storage account id (ULID), or `default` for the platform storage of this environment.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStorageAccountInput" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageAccountBodyDoc" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "insufficient_scope", "message": "A user token lacks `files:access`, a machine token carries none of `files:manage`, `files:read`, `files:config.manage`, or the route needs a scope the token does not carry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`, `storage_account_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `storage_account_in_use`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "storage_account_in_use", "message": "The storage account still holds objects, is assigned to a tenant or takes part in a migration, so it cannot be removed or have its location changed.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `storage_account_verification_failed`, `storage_adapter_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "storage_account_verification_failed", "message": "The write, read and delete probe against the storage account failed; nothing was saved.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Change a storage account (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_request", "invalid_token", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "not_found", "storage_account_not_found", "storage_account_in_use", "storage_account_verification_failed", "storage_adapter_not_allowed", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Storage accounts", "url": "/administration/storage/" } }, "delete": { "description": "Only an account no tenant, version, open upload or migration uses. The bytes in the bucket or directory are not touched. Audited.", "operationId": "StorageAccounts_remove", "parameters": [ { "name": "storage_account_id", "required": true, "in": "path", "description": "A storage account id (ULID), or `default` for the platform storage of this environment.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed." }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "insufficient_scope", "message": "A user token lacks `files:access`, a machine token carries none of `files:manage`, `files:read`, `files:config.manage`, or the route needs a scope the token does not carry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`, `storage_account_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `storage_account_in_use`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "storage_account_in_use", "message": "The storage account still holds objects, is assigned to a tenant or takes part in a migration, so it cannot be removed or have its location changed.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Remove a storage account (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_request", "invalid_token", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "not_found", "storage_account_not_found", "storage_account_in_use", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Storage accounts", "url": "/administration/storage/" } } }, "/api/v1/platform/storage-accounts/{storage_account_id}/verify": { "post": { "description": "Writes, reads and deletes a probe object and records the outcome: a failed account takes no new tenant or migration. Audited.", "operationId": "StorageAccounts_verify", "parameters": [ { "name": "storage_account_id", "required": true, "in": "path", "description": "A storage account id (ULID), or `default` for the platform storage of this environment.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageAccountVerifyBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "insufficient_scope", "message": "A user token lacks `files:access`, a machine token carries none of `files:manage`, `files:read`, `files:config.manage`, or the route needs a scope the token does not carry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`, `storage_account_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Verify a storage account (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_token", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "not_found", "storage_account_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Storage accounts", "url": "/administration/storage/" } } }, "/api/v1/platform/tenants/{tenant_id}/storage-account": { "get": { "operationId": "StorageAccounts_tenantStorage", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantStorageBodyDoc" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "A tenant's storage account and where its objects live (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_token", "not_tenant_member", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Storage accounts", "url": "/administration/storage/" } }, "put": { "description": "The tenant's new objects go to the account from now on; its existing objects stay where they are and keep being served from there. Move them with a storage migration. Audited.", "operationId": "StorageAccounts_assign", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignStorageAccountInput" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantStorageBodyDoc" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`, `storage_account_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `storage_account_not_verified`, `storage_migration_in_progress`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "storage_account_not_verified", "message": "The storage account failed its last verification, so no tenant can be assigned to it or migrated onto it.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `storage_adapter_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "storage_adapter_not_allowed", "message": "This deployment cannot use the requested storage adapter or location (a directory outside the allowed roots, a directory account where the deployment does not allow one, an endpoint on a private or link-local address).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Assign a tenant to a storage account (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "not_found", "storage_account_not_found", "storage_account_not_verified", "storage_migration_in_progress", "storage_adapter_not_allowed", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Storage accounts", "url": "/administration/storage/" } } }, "/api/v1/platform/tenants/{tenant_id}/storage-migrations": { "post": { "description": "Starts a storage migration: new objects go to the target at once; every object is copied and verified while downloads keep working (each version is read from the source until its copy is complete, then from the target); the tenant then switches to the target, and the source copies are deleted after the signed-URL grace period. No client change. Audited.", "operationId": "StorageAccounts_startMigration", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartStorageMigrationInput" } } } }, "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageMigrationBodyDoc" } } } }, "400": { "description": "Error. `error` is one of: `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 400, "error": "invalid_request", "message": "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`, `storage_account_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "409": { "description": "Error. `error` is one of: `storage_account_not_verified`, `storage_migration_in_progress`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 409, "error": "storage_account_not_verified", "message": "The storage account failed its last verification, so no tenant can be assigned to it or migrated onto it.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "422": { "description": "Error. `error` is one of: `storage_adapter_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 422, "error": "storage_adapter_not_allowed", "message": "This deployment cannot use the requested storage adapter or location (a directory outside the allowed roots, a directory account where the deployment does not allow one, an endpoint on a private or link-local address).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "Move a tenant's objects to another storage account (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_request", "invalid_token", "not_tenant_member", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "not_found", "storage_account_not_found", "storage_account_not_verified", "storage_migration_in_progress", "storage_adapter_not_allowed", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Storage accounts", "url": "/administration/storage/" } }, "get": { "operationId": "StorageAccounts_listMigrations", "parameters": [ { "name": "tenant_id", "required": true, "in": "path", "description": "The Identity Server tenant id.", "schema": { "type": "string" } }, { "name": "after", "required": false, "in": "query", "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageMigrationPageBody" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `not_tenant_member`, `tenant_not_available`, `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "not_tenant_member", "message": "The user is not an active member of the tenant in the URL.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "A tenant's storage migrations, newest first (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_token", "not_tenant_member", "tenant_not_available", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Storage accounts", "url": "/administration/storage/" } } }, "/api/v1/platform/storage-migrations/{migration_id}": { "get": { "operationId": "StorageAccounts_migration", "parameters": [ { "name": "migration_id", "required": true, "in": "path", "description": "A storage migration id (ULID).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageMigrationBodyDoc" } } } }, "401": { "description": "Error. `error` is one of: `invalid_token`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 401, "error": "invalid_token", "message": "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "403": { "description": "Error. `error` is one of: `insufficient_scope`, `client_context_mismatch`, `files_access_not_granted`, `platform_admin_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 403, "error": "insufficient_scope", "message": "A user token lacks `files:access`, a machine token carries none of `files:manage`, `files:read`, `files:config.manage`, or the route needs a scope the token does not carry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "404": { "description": "Error. `error` is one of: `not_found`, `storage_migration_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 404, "error": "not_found", "message": "An id in the path is malformed, or the route does not exist.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "429": { "description": "Error. `error` is one of: `rate_limited`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 429, "error": "rate_limited", "message": "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "503": { "description": "Error. `error` is one of: `identity_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "example": { "status_code": 503, "error": "identity_unavailable", "message": "The service could not reach the Identity Server and has no fresh cached answer.", "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "timestamp": "2026-10-22T09:12:33.120Z" } } } }, "default": { "description": "Error: see `error` for the code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "bearer": [] } ], "summary": "A storage migration and its progress (platform administrators)", "tags": [ "Settings" ], "x-audience": [ "user", "machine" ], "x-required-scopes": { "user": [ "files:access" ], "machine": [ "files:config.manage" ] }, "x-error-codes": [ "invalid_token", "insufficient_scope", "client_context_mismatch", "files_access_not_granted", "platform_admin_required", "not_found", "storage_migration_not_found", "rate_limited", "identity_unavailable" ], "externalDocs": { "description": "Storage accounts", "url": "/administration/storage/" } } } }, "info": { "title": "CCS Files API", "description": "REST API of files.centralcodestation.com: storage, folders, uploads, previews, search, permissions, shares and audit for tenant applications. Every route is under `/api/v1`; routes are kebab-case and every field is snake_case.\n\nAuthentication: a bearer access token issued by the CCS Identity Server for the Files API resource (`aud` = `files-api`).\n- **User tokens** need the `files:access` scope. A token issued to a tenant application's own client works only in that application; a client of a platform application works in any tenant the user belongs to, in a tenant application that has not switched Files off, or in its own platform application.\n- **Machine tokens** (`client_credentials`) need `files:manage` (full control of the application's storage), `files:read` (reads and download URLs) or `files:config.manage` (settings, usage, webhooks). A machine client of a tenant application works only in its own tenant and application.\n\nFile bytes never pass through the API: uploads go to signed URLs from an upload ticket, downloads and previews are short-lived signed URLs.\n\nErrors are `{ status_code, error, message, path, timestamp }`; `error` is a stable snake_case code. Lists page with `?after=&limit=`.", "version": "1.0", "contact": {} }, "tags": [ { "name": "Context", "description": "Where the caller may use Files: tenants, applications, capabilities and the public settings an uploader needs." }, { "name": "Folders", "description": "The folder tree of an application: create, list, rename, move, copy, trash and restore." }, { "name": "Uploads", "description": "Upload tickets: bytes go straight to the store with the ticket's signed URLs, never through the API." }, { "name": "Files", "description": "Files and their metadata, delivery (download, preview and batch URLs), renditions and the planned check-out." }, { "name": "Versions", "description": "Every upload to an existing file is a new immutable version." }, { "name": "Search", "description": "Search by name, keywords and filters, tags and the managed value lists." }, { "name": "Permissions", "description": "Access entries on folders and files (inherited down the tree), effective permissions, and the role matrix of the `files.*` keys stored at the Identity Server." }, { "name": "Shares", "description": "Share links with expiry, password and download limits, and their public routes." }, { "name": "Trash", "description": "Trashed folders and files, restorable within the retention." }, { "name": "Settings", "description": "Per-application storage settings, usage, the managed value lists, and platform administration." }, { "name": "Audit", "description": "The append-only log of sensitive operations." }, { "name": "Webhooks", "description": "Signed event delivery to a tenant backend." }, { "name": "Health", "description": "Liveness." } ], "servers": [ { "url": "https://files.centralcodestation.com", "description": "Production (routes are under /api/v1)" } ], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" } }, "schemas": { "ErrorBody": { "type": "object", "properties": { "status_code": { "type": "number", "example": 403 }, "error": { "type": "string", "example": "client_context_mismatch", "description": "Stable snake_case error code.", "enum": [ "invalid_request", "invalid_cursor", "invalid_limit", "invalid_json", "invalid_name", "depth_exceeded", "invalid_move", "role_locked", "invalid_redirect_uri", "invalid_id_token", "webhook_url_not_allowed", "invalid_grant", "invalid_token", "share_password_required", "insufficient_scope", "not_tenant_member", "no_application_access", "tenant_not_available", "client_context_mismatch", "principal_not_allowed", "files_access_not_granted", "missing_capability", "missing_action", "platform_admin_required", "tenant_suspended", "partial_permission", "cannot_grant_more_than_held", "tenant_owner_required", "folder_managed", "share_password_invalid", "not_found", "application_not_found", "role_not_found", "file_not_found", "folder_not_found", "upload_not_found", "version_not_found", "share_not_found", "entry_not_found", "rendition_not_available", "job_not_found", "taxonomy_not_found", "upload_expired", "upload_not_open", "name_conflict", "scan_pending", "file_quarantined", "file_trashed", "file_pending", "file_locked", "file_on_hold", "status_locked", "version_is_current", "folder_busy", "idempotency_key_reused", "share_gone", "share_limit_reached", "revision_mismatch", "file_too_large", "quota_exceeded", "payload_too_large", "upload_incomplete", "size_mismatch", "hash_mismatch", "type_not_allowed", "not_previewable", "too_many_entries", "too_many_file_ids", "too_many_scopes", "too_many_applications", "taxonomy_value_invalid", "public_visibility_disabled", "share_links_disabled", "webhook_unreachable", "rate_limited", "server_error", "not_implemented", "identity_unavailable", "storage_unavailable", "notifications_unavailable", "storage_account_not_found", "storage_migration_not_found", "storage_account_in_use", "storage_account_not_verified", "storage_migration_in_progress", "storage_account_verification_failed", "storage_adapter_not_allowed" ], "x-enum-descriptions": [ "The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent. `message` lists every problem.", "The `after` cursor is not one this service issued for this listing.", "`limit` is not a positive integer within the route's maximum.", "The request body is not valid JSON.", "A file or folder name is empty, longer than 255 characters, contains `/`, a control character, or is `.` or `..`.", "The folder would be nested deeper than 32 levels.", "A folder was moved into itself or one of its own descendants, or the root folder was moved or renamed.", "The role is `tenant_owner`, which always holds every permission and cannot be changed.", "Console sign-in only: the `redirect_uri` sent to `/auth/token` is not one of the console client's registered redirect URIs.", "Console sign-in only: no ID token was issued, or it failed validation (signature, audience, nonce) or does not belong to the access token.", "The webhook URL is not https, carries a user name or password, or points to (or resolves to) a private, loopback or link-local address.", "Console sign-in only: the authorization code or refresh token is invalid, expired, revoked or already used.", "The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (`aud` must be `files-api`).", "The share link is protected by a password and none was sent.", "A user token lacks `files:access`, a machine token carries none of `files:manage`, `files:read`, `files:config.manage`, or the route needs a scope the token does not carry.", "The user is not an active member of the tenant in the URL.", "The user has no access to the application in the URL.", "The tenant in the URL is unknown, suspended or deleted at the Identity Server.", "The token's client belongs to another tenant or application than the one in the URL, or is unknown or inactive.", "The route is for user tokens only and a machine token called it, or the other way round; or a user token sent `managed`, which only a machine client may set on a folder.", "The application switched the Files platform off at the Identity Server.", "The route needs a system-level permission key (settings, audit, the role matrix, purge) that none of the caller's roles carries in this application.", "The caller lacks the action (view, download, edit, share, delete, approve) on the item. Never says whether the item exists for someone else.", "A `/platform/*` route was called by a user the Identity Server does not report as a platform administrator, or by a machine client that is not a Files platform client with `files:config.manage`.", "A platform administrator suspended the tenant's storage: new uploads and versions are refused; reading keeps working.", "A subtree operation (delete, restore) is blocked by descendants the caller cannot act on; `blocked` lists the first 100 ids.", "An access entry names actions the granter does not hold on the item.", "Only the tenant owner may grant or withdraw `files.permissions.manage`, and release an application-managed folder (`POST P/folders/:folder_id/release-management`).", "The item is an application-managed folder or lies below one, and a person (a user token: the console, the tenant owner and `files.manage` holders included) tried to change it: upload, new version, new folder, rename, move in or out, copy into, metadata, status, trash, restore, delete, purge or permissions. Share links are refused inside a managed folder for everyone. `managed_folder_id` names the folder that carries the mark.", "The password sent for the share link is wrong. Three failures per minute per address are allowed.", "An id in the path is malformed, or the route does not exist.", "The application in the URL is not an active application of the tenant.", "The role is not a role of the tenant that may carry Files permissions in this application.", "No file with this id exists in this application, or the caller cannot view its folder.", "No folder with this id exists in this application, or the caller cannot view its parent.", "No upload ticket with this id exists for this caller in this application.", "The file has no version with this number (it may have been pruned).", "No share link with this id or token exists.", "The item has no access entry with this id of its own (inherited entries are removed on the folder that holds them).", "The requested rendition does not exist (yet) for the file's version; `rendition_status` says why.", "No job with this id exists for this caller in this application.", "Only `categories` and `departments` are managed value lists.", "The upload ticket's lifetime ended (1 hour single, 24 hours multipart).", "The ticket is already completed, being completed, or aborted.", "A sibling with the same name exists in the folder (names are compared case-insensitively).", "The application blocks downloads until the malware scan is clean, and the scan has not finished.", "The file was found infected and is quarantined: it is never served.", "The file or folder is in the trash.", "The file's upload has not been completed yet.", "Someone else holds a lock (check-out or edit session) on the file; `lock` describes it.", "The file is under a legal hold (`hold` describes it): it cannot be purged, its versions cannot be deleted or pruned, and the trash keeps it.", "The file is in review, approved or archived, and the change needs `approve` (or reopening it first).", "The current version cannot be deleted.", "The folder's subtree is being moved or copied by a background job.", "The `Idempotency-Key` was already used with a different request body.", "The share link was revoked or expired, or its target was trashed or quarantined.", "The share link reached its download limit.", "The `If-Match` revision is stale: the item changed since it was read.", "The declared size is above the application's `max_file_size_bytes`, the upload policy's, the tenant's or the platform cap.", "The upload would exceed the application's or the tenant's quota; the body carries `quota_bytes`, `used_bytes`, `reserved_bytes`.", "The JSON body is larger than 256 KiB.", "A multipart completion did not list every part, or a part is missing in the store.", "The stored object's size differs from the declared size. The object was deleted and the ticket failed.", "The stored object's SHA-256 differs from the declared `content_sha256`.", "The declared or detected type is outside the application's `allowed_types` (or the upload policy's).", "The item has nothing to preview.", "An item may carry at most 200 access entries of its own.", "More than 200 ids were sent in one batch.", "The caller's access spans more than 5,000 permission scopes, too many for one search across the application.", "The tenant has more applications than one tenant-level read or write handles.", "The application enforces its category or department list, and the value is not an active entry of it.", "`visibility: public` was requested and the application (or the tenant) does not allow public files.", "Share links are switched off for the application or the tenant.", "The webhook URL did not answer the verification ping with a 2xx within 5 seconds.", "Too many requests in the current window; `retry_after` (and the `Retry-After` header) says when to retry.", "An unexpected error in the service.", "The route is planned (check-out, check-in, edit sessions) and not served yet.", "The service could not reach the Identity Server and has no fresh cached answer.", "The object store refused or did not answer; nothing was written.", "Console only: the Notification Service token could not be obtained; live updates fall back to polling.", "No storage account has this id.", "No storage migration has this id.", "The storage account still holds objects, is assigned to a tenant or takes part in a migration, so it cannot be removed or have its location changed.", "The storage account failed its last verification, so no tenant can be assigned to it or migrated onto it.", "A storage migration of this tenant is still running.", "The write, read and delete probe against the storage account failed; nothing was saved.", "This deployment cannot use the requested storage adapter or location (a directory outside the allowed roots, a directory account where the deployment does not allow one, an endpoint on a private or link-local address)." ] }, "message": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "This client is not bound to this tenant/application" }, "path": { "type": "string", "example": "/api/v1/tenants/t1/applications/a1/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "status_code", "error", "message", "path", "timestamp" ] }, "HealthBody": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "service": { "type": "string", "example": "ccs-files" }, "version": { "type": "string" }, "object_store": { "type": "string", "example": "standard", "description": "The object store adapter." }, "content_delivery": { "type": "string", "example": "standard", "description": "The content delivery adapter." }, "processing_queue": { "type": "string", "example": "standard" }, "search_provider": { "type": "string", "example": "standard" }, "time": { "type": "string", "format": "date-time" } }, "required": [ "status", "service", "version", "object_store", "content_delivery", "processing_queue", "search_provider", "time" ] }, "MeBody": { "type": "object", "properties": { "user_id": { "type": "string" }, "platform_admin": { "type": "boolean", "description": "The Identity Server reports the `platform_admin` role for the caller." } }, "required": [ "user_id", "platform_admin" ] }, "TenantBody": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logo_url": { "type": "string", "nullable": true } }, "required": [ "tenant_id", "name", "slug", "logo_url" ] }, "TenantList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TenantBody" } } }, "required": [ "items" ] }, "ContextApplicationBody": { "type": "object", "properties": { "application_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "type": { "type": "string", "enum": [ "TENANT", "PLATFORM" ], "description": "`PLATFORM` is the calling platform client's own application (its own-platform context)." }, "files_enabled": { "type": "boolean", "description": "false when the application switched Files off: every route answers `files_access_not_granted`." } }, "required": [ "application_id", "name", "slug", "type", "files_enabled" ] }, "ContextApplicationList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContextApplicationBody" } } }, "required": [ "items" ] }, "CapabilityRoleBody": { "type": "object", "properties": { "role_id": { "type": "string", "nullable": true }, "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "TENANT", "APPLICATION" ] } }, "required": [ "role_id", "name", "scope" ] }, "CapabilitiesBody": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "application_id": { "type": "string" }, "user_id": { "type": "string", "nullable": true, "description": "null for machine principals." }, "principal_type": { "type": "string", "enum": [ "user", "machine" ] }, "tenant_owner": { "type": "boolean", "description": "The caller holds the `tenant_owner` role in the tenant." }, "roles": { "description": "The caller's roles: tenant roles plus the application's own roles. Never platform roles. Empty for machine principals.", "type": "array", "items": { "$ref": "#/components/schemas/CapabilityRoleBody" } }, "capabilities": { "example": [ "files.view", "files.download" ], "description": "The `files.*` keys the caller holds in the application, with `files.manage` and `files.configure` expanded. The tenant owner holds every key.", "type": "array", "items": { "type": "string" } } }, "required": [ "tenant_id", "application_id", "user_id", "principal_type", "tenant_owner", "roles", "capabilities" ] }, "PermissionCatalogEntryBody": { "type": "object", "properties": { "key": { "type": "string", "example": "files.view" }, "label": { "type": "string", "example": "View", "description": "The column heading the console shows." }, "description": { "type": "string" }, "group": { "type": "string", "enum": [ "content", "administration", "delegation" ], "description": "The console shows the content keys and the administration keys as two groups." }, "grants": { "description": "The keys this one expands to: only the umbrellas `files.manage` and `files.configure` grant others.", "type": "array", "items": { "type": "string" } }, "owner_only": { "type": "boolean", "description": "Only the tenant owner may grant or withdraw this key (`files.permissions.manage`)." } }, "required": [ "key", "label", "description", "group", "grants", "owner_only" ] }, "RolePermissionsItemBody": { "type": "object", "properties": { "role_id": { "type": "string" }, "name": { "type": "string", "example": "tenant_admin", "description": "The role's name at the Identity Server." }, "display_name": { "type": "string", "nullable": true, "example": "Administrator" }, "scope": { "type": "string", "enum": [ "TENANT", "APPLICATION" ], "description": "`APPLICATION`: a role of this application only." }, "system": { "type": "boolean" }, "implicit": { "type": "boolean", "description": "`tenant_owner`: holds every key, cannot be changed (`role_locked`)." }, "keys": { "description": "The keys mapped onto the role (empty for the implicit owner).", "type": "array", "items": { "type": "string" } }, "effective_keys": { "description": "What the service enforces for the role: the mapped keys with `files.manage` and `files.configure` expanded, every key for the owner.", "type": "array", "items": { "type": "string" } }, "editable": { "type": "boolean", "description": "false for the owner role, which always holds every key." } }, "required": [ "role_id", "name", "display_name", "scope", "system", "implicit", "keys", "effective_keys", "editable" ] }, "PermissionsBody": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "application_id": { "type": "string" }, "configured": { "type": "boolean", "description": "true once any role other than the owner holds a key here." }, "tenant_owner": { "type": "boolean", "description": "Whether the caller is the tenant owner (only the owner may change `files.permissions.manage`)." }, "catalog": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionCatalogEntryBody" } }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/RolePermissionsItemBody" } } }, "required": [ "tenant_id", "application_id", "configured", "tenant_owner", "catalog", "roles" ] }, "SetRolePermissionsBody": { "type": "object", "properties": { "keys": { "example": [ "files.view", "files.download" ], "description": "The complete key set of the role: an idempotent replace. Keys outside the catalog are 400.", "type": "array", "items": { "type": "string" } } }, "required": [ "keys" ] }, "ApplicationPermissionsBody": { "type": "object", "properties": { "application_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "can_manage": { "type": "boolean", "description": "The caller may manage the permissions of this application. When false, `roles` is empty." }, "configured": { "type": "boolean" }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/RolePermissionsItemBody" } } }, "required": [ "application_id", "name", "slug", "can_manage", "configured", "roles" ] }, "TenantPermissionsBody": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "tenant_owner": { "type": "boolean" }, "catalog": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionCatalogEntryBody" } }, "applications": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationPermissionsBody" } } }, "required": [ "tenant_id", "tenant_owner", "catalog", "applications" ] }, "ApplyRolePermissionsResultBody": { "type": "object", "properties": { "application_id": { "type": "string" }, "status": { "type": "string", "enum": [ "applied", "failed", "skipped" ], "description": "`skipped`: the caller may not manage this application." }, "error": { "type": "string", "nullable": true, "description": "The error code of a failed or skipped application." } }, "required": [ "application_id", "status", "error" ] }, "ApplyRolePermissionsBody": { "type": "object", "properties": { "role_id": { "type": "string" }, "name": { "type": "string" }, "display_name": { "type": "string", "nullable": true }, "keys": { "type": "array", "items": { "type": "string" } }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ApplyRolePermissionsResultBody" } }, "failed": { "type": "number" }, "skipped": { "type": "number" } }, "required": [ "role_id", "name", "display_name", "keys", "results", "failed", "skipped" ] }, "CreatedByBody": { "type": "object", "properties": { "user_id": { "type": "string", "nullable": true }, "client_id": { "type": "string" } }, "required": [ "user_id", "client_id" ] }, "ManagedByBody": { "type": "object", "properties": { "client_id": { "type": "string", "description": "The machine client that marked the managing folder." }, "name": { "type": "string", "nullable": true, "description": "A display name for it: the tenant application's name, or a platform application's slug." }, "managed_folder_id": { "type": "string", "description": "The folder that carries the mark (the item itself, or its nearest marked ancestor). The tenant owner releases this one." }, "managed_at": { "type": "string", "format": "date-time" } }, "required": [ "client_id", "name", "managed_folder_id", "managed_at" ] }, "FolderBody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "folder" ] }, "folder_id": { "type": "string", "description": "`root` for the application's root folder." }, "tenant_id": { "type": "string" }, "application_id": { "type": "string" }, "parent_id": { "type": "string", "nullable": true }, "name": { "type": "string" }, "path": { "type": "string", "example": "/posts" }, "depth": { "type": "number" }, "description": { "type": "string", "nullable": true }, "owner_id": { "type": "string", "nullable": true }, "created_by": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CreatedByBody" } ] }, "inherit": { "type": "boolean" }, "acl_scope_id": { "type": "string" }, "entries_count": { "type": "number" }, "state": { "type": "string", "enum": [ "available", "trashed" ] }, "revision": { "type": "number", "description": "Send it as `If-Match` to refuse a stale write (412 `revision_mismatch`)." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "external_ref": { "type": "string", "nullable": true }, "busy": { "type": "boolean", "description": "A background job rewrites the subtree; writes under it answer 409 `folder_busy`." }, "managed": { "type": "boolean", "description": "Application-managed: the item is a folder an application marked, or lies below one. Read-only for people (403 `folder_managed`); only the application's machine clients change it." }, "managed_by": { "nullable": true, "description": "Who manages it and which folder carries the mark; null when not managed.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ManagedByBody" } ] }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "trashed_at": { "type": "string", "format": "date-time", "nullable": true }, "trashed_by": { "type": "string", "nullable": true }, "my_actions": { "type": "array", "description": "What the caller may do with the folder.", "items": { "type": "string", "enum": [ "view", "download", "edit", "share", "delete", "approve" ] } } }, "required": [ "type", "folder_id", "tenant_id", "application_id", "parent_id", "name", "path", "depth", "description", "owner_id", "created_by", "inherit", "acl_scope_id", "entries_count", "state", "revision", "metadata", "external_ref", "busy", "managed", "managed_by", "created_at", "updated_at", "trashed_at", "trashed_by", "my_actions" ] }, "FolderPageBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FolderBody" } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "items", "next_cursor" ] }, "CreateFolderBody": { "type": "object", "properties": { "parent_id": { "type": "string", "description": "`root` or a folder id." }, "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "inherit": { "type": "boolean", "default": true }, "owner_id": { "type": "string", "description": "Machine tokens and files.manage only." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "external_ref": { "type": "string", "nullable": true }, "managed": { "type": "boolean", "description": "Machine tokens with `files:manage` only (a user token answers 403 `principal_not_allowed`): create the folder application-managed, read-only for people with its whole subtree." } }, "required": [ "parent_id", "name" ] }, "ChildrenBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/FolderBody" }, { "$ref": "#/components/schemas/FileBody" } ] } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "items", "next_cursor" ] }, "PathSegmentBody": { "type": "object", "properties": { "folder_id": { "type": "string" }, "name": { "type": "string", "nullable": true, "description": "null for a folder the caller may not view." } }, "required": [ "folder_id", "name" ] }, "PathBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PathSegmentBody" } } }, "required": [ "items" ] }, "FolderUsageBody": { "type": "object", "properties": { "bytes": { "type": "number" }, "files": { "type": "number" }, "folders": { "type": "number" } }, "required": [ "bytes", "files", "folders" ] }, "UpdateFolderBody": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "parent_id": { "type": "string", "description": "Moves the folder." }, "owner_id": { "type": "string", "description": "files.manage." }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "Merged; null removes a key." }, "external_ref": { "type": "string", "nullable": true }, "managed": { "type": "boolean", "description": "Machine tokens with `files:manage` only (a user token answers 403 `principal_not_allowed`): true marks the folder application-managed, false unmarks it. The root cannot be managed." } } }, "CopyFolderBody": { "type": "object", "properties": { "parent_id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "parent_id" ] }, "CopyFolderResultBody": { "type": "object", "properties": { "job_id": { "type": "string" }, "folder": { "$ref": "#/components/schemas/FolderBody" } }, "required": [ "job_id", "folder" ] }, "JobRefBody": { "type": "object", "properties": { "job_id": { "type": "string" } }, "required": [ "job_id" ] }, "ReleaseManagementBody": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the tenant owner releases the folder; kept in the audit log." } }, "required": [ "reason" ] }, "AccessEntryBody": { "type": "object", "properties": { "entry_id": { "type": "string" }, "principal": { "type": "object", "description": "`{ type: user, user_id }`, `{ type: role, role_id, name }` or `{ type: application }`." }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "view", "download", "edit", "share", "delete", "approve" ] } }, "granted_by": { "$ref": "#/components/schemas/CreatedByBody" }, "granted_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "inherited_from": { "type": "string", "description": "Inherited from this folder (or `root`)." } }, "required": [ "entry_id", "principal", "actions", "granted_by", "granted_at", "expires_at" ] }, "ItemPermissionsBody": { "type": "object", "properties": { "inherit": { "type": "boolean" }, "acl_scope_id": { "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/AccessEntryBody" } }, "effective": { "type": "array", "items": { "type": "object" } } }, "required": [ "inherit", "acl_scope_id", "entries", "effective" ] }, "EntryPrincipalBody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "role", "application" ] }, "user_id": { "type": "string" }, "role_id": { "type": "string" } }, "required": [ "type" ] }, "GrantEntryBody": { "type": "object", "properties": { "principal": { "$ref": "#/components/schemas/EntryPrincipalBody" }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "view", "download", "edit", "share", "delete", "approve" ] } }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "principal", "actions" ] }, "ReplacePermissionsBody": { "type": "object", "properties": { "inherit": { "type": "boolean" }, "copy_inherited": { "type": "boolean", "default": true, "description": "When breaking inheritance: copy the effective entries into the own list." }, "keep_own": { "type": "boolean", "default": false, "description": "When restoring inheritance: keep the own entries." }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/GrantEntryBody" } } } }, "CreateShareBody": { "type": "object", "properties": { "actions": { "type": "array", "default": [ "view" ], "items": { "type": "string", "enum": [ "view", "download" ] } }, "expires_at": { "type": "string", "format": "date-time", "description": "Default 7 days, at most share_link_max_days." }, "password": { "type": "string" }, "max_downloads": { "type": "number" }, "label": { "type": "string" } } }, "CreatedShareBody": { "type": "object", "properties": { "share_id": { "type": "string" }, "target": { "type": "object" }, "actions": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time" }, "password_protected": { "type": "boolean" }, "max_downloads": { "type": "number", "nullable": true }, "downloads": { "type": "number" }, "access_count": { "type": "number" }, "last_accessed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_by": { "$ref": "#/components/schemas/CreatedByBody" }, "created_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "label": { "type": "string", "nullable": true }, "token": { "type": "string", "description": "Shown once." }, "url": { "type": "string" } }, "required": [ "share_id", "target", "actions", "expires_at", "password_protected", "max_downloads", "downloads", "access_count", "last_accessed_at", "created_by", "created_at", "revoked_at", "label", "token", "url" ] }, "ShareBody": { "type": "object", "properties": { "share_id": { "type": "string" }, "target": { "type": "object" }, "actions": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time" }, "password_protected": { "type": "boolean" }, "max_downloads": { "type": "number", "nullable": true }, "downloads": { "type": "number" }, "access_count": { "type": "number" }, "last_accessed_at": { "type": "string", "format": "date-time", "nullable": true }, "created_by": { "$ref": "#/components/schemas/CreatedByBody" }, "created_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "label": { "type": "string", "nullable": true } }, "required": [ "share_id", "target", "actions", "expires_at", "password_protected", "max_downloads", "downloads", "access_count", "last_accessed_at", "created_by", "created_at", "revoked_at", "label" ] }, "ShareListBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ShareBody" } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "items" ] }, "AuditRowBody": { "type": "object", "properties": { "audit_id": { "type": "string" }, "tenant_id": { "type": "string", "nullable": true }, "application_id": { "type": "string", "nullable": true }, "at": { "type": "string", "format": "date-time" }, "actor": { "type": "object" }, "action": { "type": "string" }, "target": { "type": "object" }, "ip": { "type": "string", "nullable": true }, "user_agent": { "type": "string", "nullable": true }, "metadata": { "type": "object" } }, "required": [ "audit_id", "tenant_id", "application_id", "at", "actor", "action", "target", "ip", "user_agent", "metadata" ] }, "AuditPageBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuditRowBody" } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "items", "next_cursor" ] }, "CreateUploadBody": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "size": { "type": "number", "description": "Bytes; checked again at completion (422 `size_mismatch`)." }, "mime_type": { "type": "string", "example": "image/jpeg" }, "folder_id": { "type": "string", "default": "root" }, "content_sha256": { "type": "string", "description": "Hex SHA-256; signed into single PUTs and verified by processing." }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "custom": { "type": "object", "additionalProperties": { "type": "string" } }, "status": { "type": "string", "enum": [ "draft", "in_review", "approved", "rejected", "archived" ] }, "visibility": { "type": "string", "enum": [ "private", "application", "public" ] }, "policy": { "type": "string", "description": "A named upload policy of the application; unknown names fall back to the default (`policy_applied`)." }, "owner_id": { "type": "string", "description": "Machine tokens: the user the file belongs to." }, "acting_user_id": { "type": "string", "description": "Machine tokens: the user you act for (audit)." }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/GrantEntryBody" } }, "inherit": { "type": "boolean", "default": true }, "external_ref": { "type": "string", "nullable": true, "maxLength": 200 }, "notify_user_ids": { "description": "Who gets `file.ready` besides the owner.", "type": "array", "items": { "type": "string" } }, "on_name_conflict": { "type": "string", "enum": [ "fail", "rename" ], "default": "fail", "description": "`rename` picks \"name (1).ext\" instead of answering 409 `name_conflict`." } }, "required": [ "name", "size", "mime_type" ] }, "TicketPartBody": { "type": "object", "properties": { "part_number": { "type": "number" }, "url": { "type": "string" } }, "required": [ "part_number", "url" ] }, "UploadedPartBody": { "type": "object", "properties": { "part_number": { "type": "number" }, "etag": { "type": "string" }, "size": { "type": "number" } }, "required": [ "part_number", "etag", "size" ] }, "UploadTicketBody": { "type": "object", "properties": { "upload_id": { "type": "string" }, "file_id": { "type": "string", "description": "Known at once: store it in your own record." }, "version_no": { "type": "number" }, "status": { "type": "string", "enum": [ "open", "completing", "completed", "aborted", "expired", "failed" ] }, "policy_applied": { "type": "string" }, "method": { "type": "string", "enum": [ "put", "multipart" ] }, "url": { "type": "string", "nullable": true, "description": "`put` only: PUT the whole body here." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Send exactly these headers with the PUT, and nothing else." }, "part_size": { "type": "number", "nullable": true }, "parts_total": { "type": "number", "nullable": true }, "parts": { "nullable": true, "description": "The first 100 part URLs; `POST …/parts` for the rest.", "type": "array", "items": { "$ref": "#/components/schemas/TicketPartBody" } }, "expires_at": { "type": "string", "format": "date-time" }, "parts_uploaded": { "description": "`GET` only: the parts the store holds (resume from the first missing one).", "type": "array", "items": { "$ref": "#/components/schemas/UploadedPartBody" } } }, "required": [ "upload_id", "file_id", "version_no", "status", "policy_applied", "method", "url", "headers", "part_size", "parts_total", "parts", "expires_at" ] }, "PartUrlsBody": { "type": "object", "properties": { "parts": { "type": "array", "items": { "$ref": "#/components/schemas/TicketPartBody" } }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "parts", "expires_at" ] }, "CompletePartBody": { "type": "object", "properties": { "part_number": { "type": "number" }, "etag": { "type": "string" } }, "required": [ "part_number", "etag" ] }, "CompleteUploadBody": { "type": "object", "properties": { "parts": { "description": "Required for multipart: every part with the ETag the store answered.", "type": "array", "items": { "$ref": "#/components/schemas/CompletePartBody" } } } }, "LockBody": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "checkout", "edit_session" ] }, "holder_user_id": { "type": "string", "nullable": true }, "holder_client_id": { "type": "string", "nullable": true }, "acquired_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "note": { "type": "string", "nullable": true } }, "required": [ "kind", "holder_user_id", "holder_client_id", "acquired_at", "expires_at", "note" ] }, "HoldBody": { "type": "object", "properties": { "reason": { "type": "string" }, "placed_by": { "type": "string", "description": "The user who placed it, or the client id of a machine caller without acting_user_id." }, "placed_at": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time", "nullable": true, "description": "When the hold ends by itself; null: until released." } }, "required": [ "reason", "placed_by", "placed_at", "until" ] }, "FileBody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file" ] }, "file_id": { "type": "string" }, "tenant_id": { "type": "string" }, "application_id": { "type": "string" }, "folder_id": { "type": "string" }, "path": { "type": "string" }, "name": { "type": "string" }, "extension": { "type": "string", "nullable": true }, "mime_type": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "video", "audio", "pdf", "document", "spreadsheet", "presentation", "text", "archive", "other" ] }, "size": { "type": "number" }, "content_sha256": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "custom": { "type": "object", "additionalProperties": { "type": "string" } }, "external_ref": { "type": "string", "nullable": true, "description": "Your own reference (for example `post:123`); a list and search filter." }, "owner_id": { "type": "string", "nullable": true }, "created_by": { "$ref": "#/components/schemas/CreatedByBody" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "state": { "type": "string", "enum": [ "pending_upload", "available", "quarantined", "trashed" ] }, "status": { "type": "string", "enum": [ "draft", "in_review", "approved", "rejected", "archived" ] }, "visibility": { "type": "string", "enum": [ "private", "application", "public" ] }, "public_url": { "type": "string", "nullable": true, "description": "The stable URL of a public file." }, "current_version_no": { "type": "number" }, "versions_count": { "type": "number" }, "revision": { "type": "number" }, "media": { "type": "object", "additionalProperties": true, "description": "Derived from the bytes: width, height, duration_ms, pages, ..." }, "processing": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "pending", "done", "skipped", "failed", "clean", "infected" ] }, "description": "One outcome per processing step." }, "renditions": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/RenditionInfoBody" } }, "public_renditions": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true }, "duplicate_of": { "type": "string", "nullable": true }, "lock": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/LockBody" } ] }, "editable": { "type": "boolean" }, "hold": { "nullable": true, "description": "A legal hold: while it is in force the file cannot be purged and its versions are kept.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/HoldBody" } ] }, "managed": { "type": "boolean", "description": "Application-managed: the item is a folder an application marked, or lies below one. Read-only for people (403 `folder_managed`); only the application's machine clients change it." }, "managed_by": { "nullable": true, "description": "Who manages it and which folder carries the mark; null when not managed.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ManagedByBody" } ] }, "inherit": { "type": "boolean" }, "acl_scope_id": { "type": "string" }, "entries_count": { "type": "number" }, "trashed_at": { "type": "string", "format": "date-time", "nullable": true }, "trashed_by": { "type": "string", "nullable": true }, "my_actions": { "type": "array", "items": { "type": "string", "enum": [ "view", "download", "edit", "share", "delete", "approve" ] } } }, "required": [ "type", "file_id", "tenant_id", "application_id", "folder_id", "path", "name", "extension", "mime_type", "kind", "size", "content_sha256", "title", "description", "category", "department", "tags", "custom", "external_ref", "owner_id", "created_by", "created_at", "updated_at", "state", "status", "visibility", "public_url", "current_version_no", "versions_count", "revision", "media", "processing", "renditions", "public_renditions", "duplicate_of", "lock", "editable", "hold", "managed", "managed_by", "inherit", "acl_scope_id", "entries_count", "trashed_at", "trashed_by", "my_actions" ] }, "RenditionInfoBody": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "ready", "skipped", "failed" ] }, "mime_type": { "type": "string", "nullable": true }, "size": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "duration_ms": { "type": "number", "nullable": true }, "error": { "type": "string", "description": "Only on `skipped` and `failed`: why, e.g. `source_smaller`, `duration_exceeds_limit`, `size_exceeds_limit`, `duration_unknown`." } }, "required": [ "status", "mime_type", "size", "width", "height", "duration_ms" ] }, "UploadPolicyBody": { "type": "object", "properties": { "allowed_types": { "type": "array", "items": { "type": "string" } }, "max_file_size_bytes": { "type": "number" } }, "required": [ "allowed_types", "max_file_size_bytes" ] }, "UrlsRequestBody": { "type": "object", "properties": { "file_ids": { "maxItems": 200, "type": "array", "items": { "type": "string" } }, "rendition": { "type": "string", "enum": [ "thumbnail", "preview", "large", "poster", "pdf", "mp4_720p", "mp4_1080p", "hls" ] }, "disposition": { "type": "string", "enum": [ "attachment", "inline" ] }, "ttl_seconds": { "type": "number", "description": "Machine tokens, up to 86,400." } }, "required": [ "file_ids" ] }, "UrlItemBody": { "type": "object", "properties": { "file_id": { "type": "string" }, "url": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "error": { "type": "string", "description": "An error code; `missing_action` says nothing more about the id." } }, "required": [ "file_id" ] }, "UrlsBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UrlItemBody" } } }, "required": [ "items" ] }, "EffectivePermissionsRequestBody": { "type": "object", "properties": { "user_id": { "type": "string" }, "file_ids": { "maxItems": 200, "type": "array", "items": { "type": "string" } } }, "required": [ "user_id", "file_ids" ] }, "EffectivePermissionsItemBody": { "type": "object", "properties": { "file_id": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "view", "download", "edit", "share", "delete", "approve" ] } } }, "required": [ "file_id", "actions" ] }, "EffectivePermissionsBatchBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/EffectivePermissionsItemBody" } } }, "required": [ "items" ] }, "FilePageBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FileBody" } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "items", "next_cursor" ] }, "UpdateFileBody": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "custom": { "type": "object", "additionalProperties": { "type": "string", "nullable": true }, "description": "Merged; null removes a key." }, "status": { "type": "string", "enum": [ "draft", "in_review", "approved", "rejected", "archived" ] }, "visibility": { "type": "string", "enum": [ "private", "application", "public" ] }, "folder_id": { "type": "string", "description": "Moves the file." }, "owner_id": { "type": "string", "description": "files.manage." }, "external_ref": { "type": "string", "nullable": true }, "pinned_version_no": { "type": "number", "description": "Pins that version against pruning." }, "acting_user_id": { "type": "string", "description": "Machine tokens: the user you act for (audit)." } } }, "CopyFileBody": { "type": "object", "properties": { "folder_id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "folder_id" ] }, "RestoreFileBody": { "type": "object", "properties": { "folder_id": { "type": "string", "description": "Where to restore when the original folder is gone." } } }, "DownloadBody": { "type": "object", "properties": { "url": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "mime_type": { "type": "string" }, "size": { "type": "number" }, "name": { "type": "string" }, "version_no": { "type": "number" } }, "required": [ "url", "expires_at", "mime_type", "size", "name", "version_no" ] }, "PreviewBody": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image", "video", "audio", "pdf", "text", "none" ] }, "url": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "mime_type": { "type": "string", "nullable": true }, "renditions": { "type": "object", "additionalProperties": true }, "text": { "type": "object" }, "editable": { "type": "boolean" } }, "required": [ "kind", "url", "expires_at", "mime_type", "renditions", "editable" ] }, "VersionBody": { "type": "object", "properties": { "version_no": { "type": "number" }, "state": { "type": "string", "enum": [ "available", "rejected", "quarantined" ] }, "size": { "type": "number" }, "mime_type": { "type": "string" }, "content_sha256": { "type": "string", "nullable": true }, "created_by": { "$ref": "#/components/schemas/CreatedByBody" }, "created_at": { "type": "string", "format": "date-time" }, "comment": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "upload", "restore", "edit", "copy" ] }, "pinned": { "type": "boolean" }, "media": { "type": "object" }, "processing": { "type": "object" }, "renditions": { "type": "object" }, "current": { "type": "boolean" } }, "required": [ "version_no", "state", "size", "mime_type", "content_sha256", "created_by", "created_at", "comment", "source", "pinned", "media", "processing", "renditions", "current" ] }, "VersionPageBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/VersionBody" } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "items", "next_cursor" ] }, "CreateVersionBody": { "type": "object", "properties": { "size": { "type": "number" }, "mime_type": { "type": "string" }, "content_sha256": { "type": "string" }, "comment": { "type": "string", "nullable": true } }, "required": [ "size", "mime_type" ] }, "RestoreVersionBody": { "type": "object", "properties": { "comment": { "type": "string", "nullable": true } } }, "PatchVersionBody": { "type": "object", "properties": { "pinned": { "type": "boolean" }, "comment": { "type": "string", "nullable": true } } }, "RenditionItemBody": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "ready", "skipped", "failed" ] }, "mime_type": { "type": "string", "nullable": true }, "size": { "type": "number", "nullable": true }, "width": { "type": "number", "nullable": true }, "height": { "type": "number", "nullable": true }, "duration_ms": { "type": "number", "nullable": true }, "error": { "type": "string", "description": "Only on `skipped` and `failed`: why, e.g. `source_smaller`, `duration_exceeds_limit`, `size_exceeds_limit`, `duration_unknown`." }, "name": { "type": "string", "enum": [ "thumbnail", "preview", "large", "poster", "pdf", "mp4_720p", "mp4_1080p", "hls" ] } }, "required": [ "status", "mime_type", "size", "width", "height", "duration_ms", "name" ] }, "RenditionListBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RenditionItemBody" } } }, "required": [ "items" ] }, "RegenerateRenditionsBody": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string", "enum": [ "thumbnail", "preview", "large", "poster", "pdf", "mp4_720p", "mp4_1080p", "hls" ] } } } }, "EffectivePermissionsBody": { "type": "object", "properties": { "user_id": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "view", "download", "edit", "share", "delete", "approve" ] } }, "via": { "example": [ "role:librarian@folder:01J9…", "owner" ], "type": "array", "items": { "type": "string" } } }, "required": [ "user_id", "actions", "via" ] }, "PlaceHoldBody": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500, "description": "Why the file is held; shown to everyone who can view the file and kept in the audit log." }, "until": { "type": "string", "format": "date-time", "nullable": true, "description": "A future date when the hold ends by itself; omitted or null: until released." }, "acting_user_id": { "type": "string", "description": "Machine tokens: the member the change is recorded for." } }, "required": [ "reason" ] }, "ReleaseHoldBody": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500, "description": "Why the hold ends; kept in the audit log." }, "acting_user_id": { "type": "string", "description": "Machine tokens: the member the change is recorded for." } } }, "SearchHitBody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file" ] }, "file_id": { "type": "string" }, "tenant_id": { "type": "string" }, "application_id": { "type": "string" }, "folder_id": { "type": "string" }, "path": { "type": "string" }, "name": { "type": "string" }, "extension": { "type": "string", "nullable": true }, "mime_type": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "video", "audio", "pdf", "document", "spreadsheet", "presentation", "text", "archive", "other" ] }, "size": { "type": "number" }, "content_sha256": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "custom": { "type": "object", "additionalProperties": { "type": "string" } }, "external_ref": { "type": "string", "nullable": true, "description": "Your own reference (for example `post:123`); a list and search filter." }, "owner_id": { "type": "string", "nullable": true }, "created_by": { "$ref": "#/components/schemas/CreatedByBody" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "state": { "type": "string", "enum": [ "pending_upload", "available", "quarantined", "trashed" ] }, "status": { "type": "string", "enum": [ "draft", "in_review", "approved", "rejected", "archived" ] }, "visibility": { "type": "string", "enum": [ "private", "application", "public" ] }, "public_url": { "type": "string", "nullable": true, "description": "The stable URL of a public file." }, "current_version_no": { "type": "number" }, "versions_count": { "type": "number" }, "revision": { "type": "number" }, "media": { "type": "object", "additionalProperties": true, "description": "Derived from the bytes: width, height, duration_ms, pages, ..." }, "processing": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "pending", "done", "skipped", "failed", "clean", "infected" ] }, "description": "One outcome per processing step." }, "renditions": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/RenditionInfoBody" } }, "public_renditions": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true }, "duplicate_of": { "type": "string", "nullable": true }, "lock": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/LockBody" } ] }, "editable": { "type": "boolean" }, "hold": { "nullable": true, "description": "A legal hold: while it is in force the file cannot be purged and its versions are kept.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/HoldBody" } ] }, "managed": { "type": "boolean", "description": "Application-managed: the item is a folder an application marked, or lies below one. Read-only for people (403 `folder_managed`); only the application's machine clients change it." }, "managed_by": { "nullable": true, "description": "Who manages it and which folder carries the mark; null when not managed.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ManagedByBody" } ] }, "inherit": { "type": "boolean" }, "acl_scope_id": { "type": "string" }, "entries_count": { "type": "number" }, "trashed_at": { "type": "string", "format": "date-time", "nullable": true }, "trashed_by": { "type": "string", "nullable": true }, "my_actions": { "type": "array", "items": { "type": "string", "enum": [ "view", "download", "edit", "share", "delete", "approve" ] } }, "highlights": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "snippet": { "type": "string" } } } } }, "required": [ "type", "file_id", "tenant_id", "application_id", "folder_id", "path", "name", "extension", "mime_type", "kind", "size", "content_sha256", "title", "description", "category", "department", "tags", "custom", "external_ref", "owner_id", "created_by", "created_at", "updated_at", "state", "status", "visibility", "public_url", "current_version_no", "versions_count", "revision", "media", "processing", "renditions", "public_renditions", "duplicate_of", "lock", "editable", "hold", "managed", "managed_by", "inherit", "acl_scope_id", "entries_count", "trashed_at", "trashed_by", "my_actions" ] }, "SearchResultBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SearchHitBody" } }, "next_cursor": { "type": "string", "nullable": true }, "total": { "type": "number", "nullable": true, "description": "Exact up to 10,000, then null." }, "provider": { "type": "string" } }, "required": [ "items", "next_cursor", "total", "provider" ] }, "TagCountBody": { "type": "object", "properties": { "tag": { "type": "string" }, "count": { "type": "number" } }, "required": [ "tag", "count" ] }, "TagListBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TagCountBody" } } }, "required": [ "items" ] }, "TaxonomyValueBody": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "value", "label", "active" ] }, "TaxonomyBody": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "categories", "departments" ] }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyValueBody" } }, "enforced": { "type": "boolean", "description": "Uploads and patches must use an active value." } }, "required": [ "name", "values", "enforced" ] }, "SetTaxonomyBody": { "type": "object", "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyValueBody" } }, "enforced": { "type": "boolean" } }, "required": [ "values", "enforced" ] }, "PrincipalRoleBody": { "type": "object", "properties": { "role_id": { "type": "string" }, "name": { "type": "string" }, "display_name": { "type": "string", "nullable": true }, "scope": { "type": "string", "enum": [ "TENANT", "APPLICATION" ] }, "system": { "type": "boolean" } }, "required": [ "role_id", "name", "display_name", "scope", "system" ] }, "PrincipalRoleListBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PrincipalRoleBody" } } }, "required": [ "items" ] }, "PrincipalUserBody": { "type": "object", "properties": { "user_id": { "type": "string" }, "display_name": { "type": "string" }, "email": { "type": "string", "nullable": true } }, "required": [ "user_id", "display_name", "email" ] }, "PrincipalUserListBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PrincipalUserBody" } } }, "required": [ "items" ] }, "PublicShareBody": { "type": "object", "properties": { "target": { "type": "object" }, "actions": { "type": "array", "items": { "type": "string" } }, "password_required": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time" }, "children": { "type": "array", "items": { "type": "object" } } }, "required": [ "target", "actions", "password_required", "expires_at" ] }, "ShareDownloadRequestBody": { "type": "object", "properties": { "password": { "type": "string" }, "file_id": { "type": "string", "description": "Folder links: the file to download." }, "rendition": { "type": "string", "enum": [ "thumbnail", "preview", "large", "poster", "pdf", "mp4_720p", "mp4_1080p", "hls" ] } } }, "SignedUrlBody": { "type": "object", "properties": { "url": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "url", "expires_at" ] }, "TrashPageBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/FolderBody" }, { "$ref": "#/components/schemas/FileBody" } ] } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "items", "next_cursor" ] }, "PublicSettingsBody": { "type": "object", "properties": { "max_file_size_bytes": { "type": "number" }, "allowed_types": { "type": "array", "items": { "type": "string" } }, "upload_policies": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UploadPolicyBody" } }, "public_visibility_enabled": { "type": "boolean" }, "approvals_enabled": { "type": "boolean" }, "share_links_enabled": { "type": "boolean" }, "single_put_max_bytes": { "type": "number" } }, "required": [ "max_file_size_bytes", "allowed_types", "upload_policies", "public_visibility_enabled", "approvals_enabled", "share_links_enabled", "single_put_max_bytes" ] }, "SettingsBody": { "type": "object", "properties": { "quota_bytes": { "type": "number", "nullable": true }, "max_file_size_bytes": { "type": "number" }, "allowed_types": { "type": "array", "items": { "type": "string" } }, "upload_policies": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/UploadPolicyBody" } }, "type_mismatch_policy": { "type": "string", "enum": [ "reject", "trust_detected", "trust_declared" ] }, "scan_policy": { "type": "string", "enum": [ "block_until_clean", "async", "off" ] }, "scan_failed_policy": { "type": "string", "enum": [ "block", "allow" ] }, "scan_oversize_policy": { "type": "string", "enum": [ "allow", "block" ] }, "image_metadata": { "type": "string", "enum": [ "strip", "keep" ] }, "renditions_enabled": { "type": "boolean" }, "text_extraction_enabled": { "type": "boolean" }, "public_visibility_enabled": { "type": "boolean" }, "default_visibility": { "type": "string", "enum": [ "private", "application", "public" ] }, "owner_actions": { "type": "array", "items": { "type": "string", "enum": [ "view", "download", "edit", "share", "delete", "approve" ] } }, "owner_can_purge": { "type": "boolean" }, "approvals_enabled": { "type": "boolean" }, "share_links_enabled": { "type": "boolean" }, "share_link_max_days": { "type": "number" }, "share_base_url": { "type": "string", "nullable": true }, "trash_retention_days": { "type": "number" }, "max_versions": { "type": "number" }, "version_retention_days": { "type": "number" }, "checkout_max_days": { "type": "number" }, "download_url_ttl_seconds": { "type": "number" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_by": { "type": "string", "nullable": true } }, "required": [ "quota_bytes", "max_file_size_bytes", "allowed_types", "upload_policies", "type_mismatch_policy", "scan_policy", "scan_failed_policy", "scan_oversize_policy", "image_metadata", "renditions_enabled", "text_extraction_enabled", "public_visibility_enabled", "default_visibility", "owner_actions", "owner_can_purge", "approvals_enabled", "share_links_enabled", "share_link_max_days", "share_base_url", "trash_retention_days", "max_versions", "version_retention_days", "checkout_max_days", "download_url_ttl_seconds", "updated_at", "updated_by" ] }, "DailyUsageBody": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "The UTC day." }, "bytes": { "type": "number" }, "rendition_bytes": { "type": "number" }, "trashed_bytes": { "type": "number" }, "files": { "type": "number" }, "versions": { "type": "number" }, "quota_bytes": { "type": "number", "nullable": true, "description": "The quota in force that day; null: unlimited." } }, "required": [ "date", "bytes", "rendition_bytes", "trashed_bytes", "files", "versions", "quota_bytes" ] }, "UsageBody": { "type": "object", "properties": { "bytes": { "type": "number" }, "rendition_bytes": { "type": "number" }, "reserved_bytes": { "type": "number" }, "trashed_bytes": { "type": "number" }, "files": { "type": "number" }, "versions": { "type": "number" }, "quota_bytes": { "type": "number", "nullable": true }, "tenant_quota_bytes": { "type": "number", "nullable": true }, "tenant_used_bytes": { "type": "number" }, "reconciled_at": { "type": "string", "format": "date-time", "nullable": true }, "by_kind": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "bytes": { "type": "number" }, "files": { "type": "number" } } }, "description": "Bytes by kind (trash included)." }, "by_folder": { "type": "array", "items": { "type": "object", "properties": { "folder_id": { "type": "string" }, "path": { "type": "string" }, "bytes": { "type": "number" }, "files": { "type": "number" } } }, "description": "The 20 folders holding the most bytes directly." }, "daily": { "description": "The last 30 days from the daily usage snapshots, oldest first; days without a snapshot are absent.", "type": "array", "items": { "$ref": "#/components/schemas/DailyUsageBody" } } }, "required": [ "bytes", "rendition_bytes", "reserved_bytes", "trashed_bytes", "files", "versions", "quota_bytes", "tenant_quota_bytes", "tenant_used_bytes", "reconciled_at", "by_kind", "by_folder", "daily" ] }, "TenantUsageBody": { "type": "object", "properties": { "quota_bytes": { "type": "number", "nullable": true }, "used_bytes": { "type": "number" }, "applications": { "type": "array", "items": { "type": "object", "properties": { "application_id": { "type": "string" }, "bytes": { "type": "number" }, "quota_bytes": { "type": "number", "nullable": true } } } } }, "required": [ "quota_bytes", "used_bytes", "applications" ] }, "JobBody": { "type": "object", "properties": { "job_id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] }, "progress": { "type": "object", "nullable": true }, "result": { "type": "object", "nullable": true }, "error": { "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "job_id", "type", "status", "progress", "result", "error", "created_at", "updated_at" ] }, "PlatformTenantBody": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "quota_bytes": { "type": "number", "nullable": true }, "used_bytes": { "type": "number" }, "reserved_bytes": { "type": "number" }, "trashed_bytes": { "type": "number" }, "files": { "type": "number" }, "applications": { "type": "number" }, "suspended": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "tenant_id", "name", "slug", "status", "quota_bytes", "used_bytes", "reserved_bytes", "trashed_bytes", "files", "applications", "suspended", "updated_at" ] }, "PlatformTenantPageBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformTenantBody" } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "items", "next_cursor" ] }, "TenantSettingsBody": { "type": "object", "properties": { "quota_bytes": { "type": "number", "nullable": true, "description": "null: unlimited." }, "max_file_size_bytes": { "type": "number", "nullable": true }, "allowed_types": { "nullable": true, "type": "array", "items": { "type": "string" } }, "public_visibility_allowed": { "type": "boolean" }, "share_links_allowed": { "type": "boolean" }, "suspended": { "type": "boolean", "description": "Every new ticket answers 403 `tenant_suspended`; reads keep working." }, "note": { "type": "string", "nullable": true }, "storage_account_id": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_by": { "type": "string", "nullable": true } }, "required": [ "quota_bytes", "max_file_size_bytes", "allowed_types", "public_visibility_allowed", "share_links_allowed", "suspended", "note", "storage_account_id", "updated_at", "updated_by" ] }, "PlatformApplicationUsageBody": { "type": "object", "properties": { "application_id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "bytes": { "type": "number" }, "quota_bytes": { "type": "number", "nullable": true }, "files": { "type": "number" }, "files_enabled": { "type": "boolean", "nullable": true } }, "required": [ "application_id", "name", "bytes", "quota_bytes", "files", "files_enabled" ] }, "PlatformTenantDetailBody": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "quota_bytes": { "type": "number", "nullable": true }, "used_bytes": { "type": "number" }, "reserved_bytes": { "type": "number" }, "trashed_bytes": { "type": "number" }, "files": { "type": "number" }, "suspended": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "settings": { "$ref": "#/components/schemas/TenantSettingsBody" }, "applications": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformApplicationUsageBody" } } }, "required": [ "tenant_id", "name", "slug", "status", "quota_bytes", "used_bytes", "reserved_bytes", "trashed_bytes", "files", "suspended", "updated_at", "settings", "applications" ] }, "PlatformDefaultsBody": { "type": "object", "properties": { "default_tenant_quota_bytes": { "type": "number", "nullable": true }, "max_file_size_bytes": { "type": "number" }, "default_allowed_types": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_by": { "type": "string", "nullable": true } }, "required": [ "default_tenant_quota_bytes", "max_file_size_bytes", "default_allowed_types", "updated_at", "updated_by" ] }, "PlatformUsageTotalsDayBody": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "bytes": { "type": "number" }, "files": { "type": "number" }, "tenants": { "type": "number", "description": "Tenants with a snapshot that day." } }, "required": [ "date", "bytes", "files", "tenants" ] }, "PlatformUsageTotalsBody": { "type": "object", "properties": { "tenants": { "type": "number" }, "used_bytes": { "type": "number" }, "files": { "type": "number" }, "over_quota": { "type": "number", "description": "Tenants at or above their quota." }, "near_quota": { "type": "number", "description": "Tenants at 90% of their quota or more, below it." }, "daily": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformUsageTotalsDayBody" } } }, "required": [ "tenants", "used_bytes", "files", "over_quota", "near_quota", "daily" ] }, "TenantTrendPointBody": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "bytes": { "type": "number" }, "files": { "type": "number" } }, "required": [ "date", "bytes", "files" ] }, "PlatformTenantTrendBody": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "suspended": { "type": "boolean" }, "quota_bytes": { "type": "number", "nullable": true, "description": "null: unlimited." }, "used_bytes": { "type": "number" }, "reserved_bytes": { "type": "number" }, "files": { "type": "number" }, "start_bytes": { "type": "number", "nullable": true, "description": "Bytes on the first snapshot of the window." }, "growth_bytes": { "type": "number", "nullable": true, "description": "The last snapshot of the window minus the first." }, "growth_ratio": { "type": "number", "nullable": true, "description": "`growth_bytes / start_bytes`; null when the window starts at 0." }, "quota_ratio": { "type": "number", "nullable": true, "description": "`(used_bytes + reserved_bytes) / quota_bytes`; null when unlimited." }, "daily": { "type": "array", "items": { "$ref": "#/components/schemas/TenantTrendPointBody" } } }, "required": [ "tenant_id", "name", "slug", "suspended", "quota_bytes", "used_bytes", "reserved_bytes", "files", "start_bytes", "growth_bytes", "growth_ratio", "quota_ratio", "daily" ] }, "PlatformUsageTrendsBody": { "type": "object", "properties": { "days": { "type": "number" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "sort": { "type": "string", "enum": [ "used_bytes", "growth_bytes", "quota_ratio" ] }, "totals": { "$ref": "#/components/schemas/PlatformUsageTotalsBody" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformTenantTrendBody" } } }, "required": [ "days", "from", "to", "sort", "totals", "items" ] }, "PlatformApplicationTrendBody": { "type": "object", "properties": { "application_id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "daily": { "type": "array", "items": { "$ref": "#/components/schemas/DailyUsageBody" } } }, "required": [ "application_id", "name", "daily" ] }, "PlatformTenantUsageTrendBody": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "days": { "type": "number" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "daily": { "description": "The tenant (every application together).", "type": "array", "items": { "$ref": "#/components/schemas/DailyUsageBody" } }, "applications": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformApplicationTrendBody" } } }, "required": [ "tenant_id", "name", "days", "from", "to", "daily", "applications" ] }, "WebhookConfig": { "type": "object", "properties": { "url": { "type": "string", "nullable": true, "example": "https://api.example.com/hooks/files", "description": "null when no webhook is set." }, "events": { "example": [ "file.ready", "file.failed" ], "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean", "description": "false when switched off, or after 20 consecutive failed deliveries." }, "secret_set": { "type": "boolean", "description": "Whether a secret is stored (the secret itself is never returned)." }, "consecutive_failures": { "type": "number", "description": "Consecutive events whose every attempt failed; 20 switch the webhook off. Reset by a delivery or a PUT." }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true }, "disabled_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the failures switched it off." }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "url", "events", "active", "secret_set", "consecutive_failures", "last_delivery_at", "disabled_at", "updated_at" ] }, "WebhookInput": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "example": "https://api.example.com/hooks/files", "description": "https in production; no credentials; not a private, loopback or link-local address." }, "secret": { "type": "string", "minLength": 16, "maxLength": 256, "writeOnly": true, "description": "Signs every delivery (`X-Files-Signature`). Write-only, stored encrypted, never returned. Required the first time; leave it out to keep the stored one." }, "events": { "type": "array", "example": [ "file.ready", "file.failed" ], "items": { "type": "string", "enum": [ "file.ready", "file.failed", "file.quarantined", "file.status.changed", "file.shared", "file.version.created", "file.lock.changed", "folder.changed" ] } }, "active": { "type": "boolean", "default": true, "description": "An active webhook is pinged before it is saved; `false` stops deliveries without a ping." } }, "required": [ "url", "events" ] }, "WebhookDelivery": { "type": "object", "properties": { "delivery_id": { "type": "string", "description": "The attempt's `X-Files-Delivery` (ULID)." }, "event_id": { "type": "string", "description": "The event's `id`, the same on every attempt: deduplicate on it." }, "event": { "type": "string", "example": "file.ready" }, "attempt": { "type": "number", "minimum": 1, "maximum": 5 }, "status": { "type": "string", "enum": [ "delivered", "retrying", "failed" ], "description": "`retrying`: failed, another attempt is scheduled; `failed`: final." }, "response_code": { "type": "number", "nullable": true, "description": "The HTTP status the endpoint answered; null when it did not answer." }, "error": { "type": "string", "nullable": true, "example": "answered 503" }, "duration_ms": { "type": "number", "nullable": true }, "next_attempt_at": { "type": "string", "format": "date-time", "nullable": true }, "at": { "type": "string", "format": "date-time" } }, "required": [ "delivery_id", "event_id", "event", "attempt", "status", "response_code", "error", "duration_ms", "next_attempt_at", "at" ] }, "WebhookDeliveryPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "items", "next_cursor" ] }, "StorageAccountSettingsBody": { "type": "object", "properties": { "bucket": { "type": "string", "nullable": true, "description": "Bucket accounts: the bucket." }, "region": { "type": "string", "nullable": true, "description": "Bucket accounts: the region (`auto` for stores without regions)." }, "endpoint": { "type": "string", "nullable": true, "description": "Bucket accounts: the endpoint of the object store; null is the platform's default provider." }, "force_path_style": { "type": "boolean", "description": "Bucket accounts: path-style addressing (most self-run object stores need it)." }, "public_base_url": { "type": "string", "nullable": true, "description": "Bucket accounts: the public base URL of public copies (a CDN in front of the bucket); null is the bucket's own URL." }, "root": { "type": "string", "nullable": true, "description": "Directory accounts (`adapter: filesystem`): the root directory, inside one of the roots the operator allowed." } } }, "StorageAccountBodyDoc": { "type": "object", "properties": { "storage_account_id": { "type": "string", "description": "`default` (the platform storage of this environment) or a ULID." }, "name": { "type": "string" }, "adapter": { "type": "string", "description": "The kind of account: a bucket account, `filesystem` for a directory account; `local` and `memory` are development only." }, "delivery": { "type": "string", "description": "How the account's objects are delivered." }, "default": { "type": "boolean" }, "settings": { "$ref": "#/components/schemas/StorageAccountSettingsBody" }, "credentials_set": { "type": "boolean", "description": "Credentials are stored (encrypted, never returned)." }, "access_key_id_hint": { "type": "string", "nullable": true, "description": "The last four characters of the access key id." }, "status": { "type": "string", "enum": [ "verified", "failed" ] }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "last_error": { "type": "string", "nullable": true, "description": "Why the last verification failed." }, "tenants": { "type": "number", "description": "Tenants assigned to the account." }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "storage_account_id", "name", "adapter", "delivery", "default", "settings", "credentials_set", "access_key_id_hint", "status", "verified_at", "last_error", "tenants", "created_at", "updated_at" ] }, "StorageAccountPageBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/StorageAccountBodyDoc" } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "items", "next_cursor" ] }, "StorageAccountCredentialsInput": { "type": "object", "properties": { "access_key_id": { "type": "string" }, "secret_access_key": { "type": "string", "description": "Write-only: encrypted at rest, never returned." } }, "required": [ "access_key_id", "secret_access_key" ] }, "CreateStorageAccountInput": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "adapter": { "type": "string" }, "settings": { "$ref": "#/components/schemas/StorageAccountSettingsBody" }, "credentials": { "description": "Required for a bucket account.", "allOf": [ { "$ref": "#/components/schemas/StorageAccountCredentialsInput" } ] } }, "required": [ "name", "adapter", "settings" ] }, "UpdateStorageAccountInput": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "settings": { "description": "Merged into the current settings; the location changes only while nothing uses the account.", "allOf": [ { "$ref": "#/components/schemas/StorageAccountSettingsBody" } ] }, "credentials": { "description": "New credentials (rotation).", "allOf": [ { "$ref": "#/components/schemas/StorageAccountCredentialsInput" } ] } } }, "StorageProbeBody": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string", "nullable": true }, "duration_ms": { "type": "number" } }, "required": [ "ok", "error", "duration_ms" ] }, "StorageAccountVerifyBody": { "type": "object", "properties": { "storage_account_id": { "type": "string", "description": "`default` (the platform storage of this environment) or a ULID." }, "name": { "type": "string" }, "adapter": { "type": "string", "description": "The kind of account: a bucket account, `filesystem` for a directory account; `local` and `memory` are development only." }, "delivery": { "type": "string", "description": "How the account's objects are delivered." }, "default": { "type": "boolean" }, "settings": { "$ref": "#/components/schemas/StorageAccountSettingsBody" }, "credentials_set": { "type": "boolean", "description": "Credentials are stored (encrypted, never returned)." }, "access_key_id_hint": { "type": "string", "nullable": true, "description": "The last four characters of the access key id." }, "status": { "type": "string", "enum": [ "verified", "failed" ] }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "last_error": { "type": "string", "nullable": true, "description": "Why the last verification failed." }, "tenants": { "type": "number", "description": "Tenants assigned to the account." }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "probe": { "$ref": "#/components/schemas/StorageProbeBody" } }, "required": [ "storage_account_id", "name", "adapter", "delivery", "default", "settings", "credentials_set", "access_key_id_hint", "status", "verified_at", "last_error", "tenants", "created_at", "updated_at", "probe" ] }, "TenantStorageObjectsBody": { "type": "object", "properties": { "storage_account_id": { "type": "string" }, "versions": { "type": "number" }, "bytes": { "type": "number", "description": "Originals and renditions." } }, "required": [ "storage_account_id", "versions", "bytes" ] }, "TenantStorageBodyDoc": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "storage_account_id": { "type": "string", "description": "The account assigned to the tenant (`default`: the platform storage)." }, "write_storage_account_id": { "type": "string", "description": "Where new objects go now: the assigned account, or a running migration's target." }, "migration_id": { "type": "string", "nullable": true }, "objects": { "description": "The tenant's versions per account they live in.", "type": "array", "items": { "$ref": "#/components/schemas/TenantStorageObjectsBody" } } }, "required": [ "tenant_id", "storage_account_id", "write_storage_account_id", "migration_id", "objects" ] }, "AssignStorageAccountInput": { "type": "object", "properties": { "storage_account_id": { "type": "string", "nullable": true, "description": "An account id, or `default` (or null) for the platform storage." } }, "required": [ "storage_account_id" ] }, "StartStorageMigrationInput": { "type": "object", "properties": { "target_storage_account_id": { "type": "string", "description": "The account to move the tenant's objects to, or `default`." } }, "required": [ "target_storage_account_id" ] }, "StorageMigrationProgressBody": { "type": "object", "properties": { "versions_total": { "type": "number" }, "versions_moved": { "type": "number" }, "objects_copied": { "type": "number" }, "bytes_copied": { "type": "number" }, "objects_verified": { "type": "number" }, "objects_deleted": { "type": "number" }, "versions_waiting": { "type": "number", "description": "Versions still waiting for an open upload on another account." } }, "required": [ "versions_total", "versions_moved", "objects_copied", "bytes_copied", "objects_verified", "objects_deleted", "versions_waiting" ] }, "StorageMigrationErrorBody": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "StorageMigrationBodyDoc": { "type": "object", "properties": { "migration_id": { "type": "string" }, "tenant_id": { "type": "string" }, "source_storage_account_id": { "type": "string" }, "target_storage_account_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] }, "phase": { "type": "string", "enum": [ "copying", "verifying", "waiting", "deleting", "done", "failed" ] }, "progress": { "$ref": "#/components/schemas/StorageMigrationProgressBody" }, "switched_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the tenant switched to the target." }, "delete_after": { "type": "string", "format": "date-time", "nullable": true, "description": "When the source copies may be deleted (signed URLs minted before the switch expire by then)." }, "error": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/StorageMigrationErrorBody" } ] }, "created_by": { "$ref": "#/components/schemas/CreatedByBody" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "migration_id", "tenant_id", "source_storage_account_id", "target_storage_account_id", "status", "phase", "progress", "switched_at", "delete_after", "error", "created_by", "created_at", "updated_at", "finished_at" ] }, "StorageMigrationPageBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/StorageMigrationBodyDoc" } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "items", "next_cursor" ] } } } }