{ "openapi": "3.1.0", "info": { "title": "Freedam API", "version": "1.0.0", "description": "The Freedam API gives you programmatic access to your entire digital asset library. Search, upload, organize, and distribute assets \u2014 integrate Freedam into your content pipelines, automate metadata workflows, or build custom frontends on top of your DAM.\n\n## What you can do\n\n- **Assets** \u2014 Search with full-text and AI-powered hybrid queries, filter by metadata, update fields, and manage lifecycle\n- **Collections** \u2014 Create, organize, and curate asset collections programmatically\n- **Uploads** \u2014 Ingest files in batches with automatic metadata extraction, virus scanning, and AI enrichment\n- **Shares** \u2014 Generate secure share links with granular permissions, expiration, and access controls\n- **Operations** \u2014 Run long-running bulk actions (updates, deletes, exports) and track progress\n- **Webhooks** \u2014 Subscribe to real-time events (asset created, uploaded, shared, etc.) with signed payloads\n- **Metadata** \u2014 Read vocabulary definitions, terms, and field schemas for your tenant\n\n## Authentication\n\nAll endpoints require a Bearer token. Create one at **Settings \u2192 API Tokens**, then pass it as:\n\n```\nAuthorization: Bearer \n```\n\nTokens are scoped \u2014 each token only grants access to the abilities you assign (e.g. `assets:read`, `uploads:manage`). Rate limited to 60 requests\/minute per token.\n\n## SDKs\n\n- **TypeScript SDK** \u2014 [`@freedam\/sdk`](https:\/\/github.com\/freedam\/freedam) on npm. Typed client with full endpoint coverage, ships ESM and CJS, tracks the API release-by-release.\n- **Other languages** \u2014 Download the [OpenAPI document](\/docs\/api.json) and use it with whichever codegen tooling fits your team. The spec is the contract." }, "servers": [ { "url": "https:\/\/freedam.io\/api\/v1" } ], "security": [ { "http": [] } ], "paths": { "\/user": { "get": { "operationId": "v1.user", "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/tokens": { "get": { "operationId": "v1.tokens.index", "summary": "List the authenticated user's API tokens", "tags": [ "ApiToken" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "abilities": { "type": "string" }, "description": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ] }, "last_used_ip": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "abilities", "description", "last_used_at", "last_used_ip", "expires_at", "created_at" ] } } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "v1.tokens.store", "description": "Validates that requested abilities don't exceed the user's permissions.\nThe plain text token is only returned once at creation time.", "summary": "Create a new API token", "tags": [ "ApiToken" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateApiTokenRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 201 } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/tokens\/{token}": { "delete": { "operationId": "v1.tokens.destroy", "summary": "Revoke (delete) a specific API token", "tags": [ "ApiToken" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Token revoked." } }, "required": [ "message" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Token not found." } }, "required": [ "message" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/assets": { "get": { "operationId": "v1.assets.index", "description": "Supports full-text search via `q`, shorthand filters (`asset_class_id`, `mime_type`),\nand an advanced rule engine via the `filters` JSON parameter. All filter types can be combined.", "summary": "Search and list assets", "tags": [ "Asset" ], "parameters": [ { "name": "q", "in": "query", "description": "Full-text search query \u2014 finds matches by meaning and keywords.", "schema": { "type": [ "string", "null" ], "maxLength": 500 } }, { "name": "sort_by", "in": "query", "description": "Sort field. Use `relevance` when searching with `q`.", "schema": { "type": [ "string", "null" ], "enum": [ "created_at", "updated_at", "title", "original_filename", "size", "relevance", null ] } }, { "name": "sort_direction", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "asc", "desc", null ] } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 } }, { "name": "asset_class_id", "in": "query", "description": "Shorthand filter: restrict results to a specific asset class.", "schema": { "type": [ "integer", "null" ] } }, { "name": "mime_type", "in": "query", "description": "Shorthand filter: restrict results by MIME type substring (e.g. `image\/jpeg`, `video`).", "schema": { "type": [ "string", "null" ], "maxLength": 100 }, "example": "image\/jpeg" }, { "name": "filters", "in": "query", "description": "Advanced filter rules as a JSON string. Supports single rules and nested groups with AND\/OR logic. **Single rule:** `{\"type\":\"filter\",\"field\":\"asset.title\",\"operator\":\"contains\",\"value\":\"sunset\"}`\n\n**AND group:**\n`{\"type\":\"group\",\"operator\":\"and\",\"rules\":[{\"type\":\"filter\",\"field\":\"asset.file_category\",\"operator\":\"equals\",\"value\":\"Image\"},{\"type\":\"filter\",\"field\":\"asset.width\",\"operator\":\"greater_than\",\"value\":1920}]}`\n\n**OR group:**\n`{\"type\":\"group\",\"operator\":\"or\",\"rules\":[{\"type\":\"filter\",\"field\":\"asset.mime_type\",\"operator\":\"contains\",\"value\":\"image\/jpeg\"},{\"type\":\"filter\",\"field\":\"asset.mime_type\",\"operator\":\"contains\",\"value\":\"image\/png\"}]}`\n\n**Operators:** `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `greater_than`, `greater_than_or_equal`, `less_than`, `less_than_or_equal`, `in` (array), `not_in` (array), `between` (array [min,max]), `is_empty`, `is_not_empty`, `hybrid_search`, `exact_search`, `color_equals`, `color_near`.\n\n**Common fields:** `asset.title`, `asset.original_filename`, `asset.mime_type`, `asset.file_category` (Image, Video, Audio, Document), `asset.extension`, `asset.width`, `asset.height`, `asset.file_size`, `asset.created_at`, `asset.updated_at`, `asset.capture_date`, `asset.creator`, `asset.copyright`, `asset.keywords`, `asset.ai_caption`, `asset.ai_tags`, `asset.ocr_text`, `asset.workflow_status`, `asset.collections` (with `in`\/`not_in`), `metadata.{key}` (custom metadata fields).", "schema": { "type": [ "string", "null" ], "maxLength": 65536 }, "example": [ { "type": "filter", "field": "asset.file_category", "operator": "equals", "value": "Image" } ] }, { "name": "ingestion_batch_id", "in": "query", "description": "Restrict results to assets from a specific upload batch.", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "`AssetCollection`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AssetCollection" } }, "required": [ "data" ] } } } }, "403": { "description": "Token does not have the required abilities: assets:read", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/assets\/{gaid}": { "get": { "operationId": "v1.assets.show", "summary": "Show a single asset by GAID", "tags": [ "Asset" ], "parameters": [ { "name": "gaid", "in": "path", "required": true, "description": "The Global Asset ID (GAID) of the asset.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`AssetResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/AssetResource" }, { "type": "object", "required": [ "collections", "owner", "created_by", "updated_by" ] } ] } }, "required": [ "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Asset not found." } }, "required": [ "message" ] } } } }, "403": { "description": "Token does not have the required abilities: assets:read", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "v1.assets.update", "summary": "Update an asset", "tags": [ "Asset" ], "parameters": [ { "name": "gaid", "in": "path", "required": true, "description": "The Global Asset ID (GAID) of the asset.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateAssetRequest" } } } }, "responses": { "422": { "$ref": "#\/components\/responses\/ValidationException" }, "200": { "description": "`AssetResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AssetResource" } }, "required": [ "data" ] } } } }, "403": { "description": "Token does not have the required abilities: assets:write", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "delete": { "operationId": "v1.assets.destroy", "summary": "Soft-delete an asset", "tags": [ "Asset" ], "parameters": [ { "name": "gaid", "in": "path", "required": true, "description": "The Global Asset ID (GAID) of the asset.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Asset deleted." } }, "required": [ "message" ] } } } }, "403": { "description": "Token does not have the required abilities: assets:delete", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/assets\/{gaid}\/embed": { "get": { "operationId": "v1.assets.embed.show", "summary": "Show the existing embed code for a video asset, if one exists", "tags": [ "AssetEmbed" ], "parameters": [ { "name": "gaid", "in": "path", "required": true, "description": "The Global Asset ID (GAID) of the video asset.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`AssetEmbedResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AssetEmbedResource" } }, "required": [ "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No embed code exists for this asset." } }, "required": [ "message" ] } } } }, "403": { "description": "Token does not have the required abilities: shares:read", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "v1.assets.embed.store", "description": "Reuses an existing active embed share when one exists for the\nauthenticated user, refreshing its expiration if it is approaching\nthe threshold. Pass `force_new=true` to revoke the previous share\nand mint a fresh one.", "summary": "Generate (or refresh) an embed code for a video asset", "tags": [ "AssetEmbed" ], "parameters": [ { "name": "gaid", "in": "path", "required": true, "description": "The Global Asset ID (GAID) of the video asset.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateAssetEmbedRequest" } } } }, "responses": { "201": { "description": "`AssetEmbedResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AssetEmbedResource" } }, "required": [ "data" ] } } } }, "403": { "description": "Token does not have the required abilities: shares:manage", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "v1.assets.embed.destroy", "summary": "Revoke the embed code for a video asset", "tags": [ "AssetEmbed" ], "parameters": [ { "name": "gaid", "in": "path", "required": true, "description": "The Global Asset ID (GAID) of the video asset.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Embed code revoked." } }, "required": [ "message" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No embed code exists for this asset." } }, "required": [ "message" ] } } } }, "403": { "description": "Token does not have the required abilities: shares:manage", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/collections": { "get": { "operationId": "v1.collections.index", "summary": "List collections with optional filters, scoped to the collections the\nrequesting user may view per `CollectionPolicy::view()`", "tags": [ "Collection" ], "parameters": [ { "name": "collection_type_id", "in": "query", "schema": { "type": "string" } }, { "name": "parent_id", "in": "query", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 24 } } ], "responses": { "200": { "description": "Paginated set of `CollectionResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/CollectionCollection" }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "403": { "description": "Token does not have the required abilities: collections:read", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "v1.collections.store", "summary": "Create a new collection", "tags": [ "Collection" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateCollectionRequest" } } } }, "responses": { "422": { "$ref": "#\/components\/responses\/ValidationException" }, "201": { "description": "`CollectionResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/CollectionResource" }, { "type": "object", "required": [ "created_by" ] } ] } }, "required": [ "data" ] } } } }, "403": { "description": "Token does not have the required abilities: collections:write", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/collections\/{collection}": { "get": { "operationId": "v1.collections.show", "summary": "Show a single collection", "tags": [ "Collection" ], "parameters": [ { "name": "collection", "in": "path", "required": true, "description": "The collection ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`CollectionResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/CollectionResource" }, { "type": "object", "required": [ "parent", "children", "created_by", "updated_by" ] } ] } }, "required": [ "data" ] } } } }, "403": { "description": "Token does not have the required abilities: collections:read", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "v1.collections.update", "summary": "Update a collection", "tags": [ "Collection" ], "parameters": [ { "name": "collection", "in": "path", "required": true, "description": "The collection ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateCollectionRequest" } } } }, "responses": { "422": { "$ref": "#\/components\/responses\/ValidationException" }, "200": { "description": "`CollectionResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/CollectionResource" }, { "type": "object", "required": [ "parent", "created_by", "updated_by" ] } ] } }, "required": [ "data" ] } } } }, "403": { "description": "Token does not have the required abilities: collections:write", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "delete": { "operationId": "v1.collections.destroy", "summary": "Delete a collection", "tags": [ "Collection" ], "parameters": [ { "name": "collection", "in": "path", "required": true, "description": "The collection ID", "schema": { "type": "integer" } } ], "responses": { "422": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Failed to delete collection." } }, "required": [ "message" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Collection cannot be deleted due to a conflict." } }, "required": [ "message" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Collection deleted." } }, "required": [ "message" ] } } } }, "403": { "description": "Token does not have the required abilities: collections:delete", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/collections\/{collection}\/assets": { "post": { "operationId": "v1.collections.assets.add", "summary": "Add assets to a collection", "tags": [ "Collection" ], "parameters": [ { "name": "collection", "in": "path", "required": true, "description": "The collection ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ManageCollectionAssetsRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "succeeded": { "type": "integer" }, "failed": { "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "errors": { "anyOf": [ { "type": "array", "prefixItems": [ { "type": "object", "properties": { "id": { "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "error" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false }, { "type": "string" } ] } }, "required": [ "message", "succeeded", "failed", "errors" ] } } } }, "403": { "description": "Token does not have the required abilities: collections:write", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "v1.collections.assets.remove", "summary": "Remove assets from a collection", "tags": [ "Collection" ], "parameters": [ { "name": "collection", "in": "path", "required": true, "description": "The collection ID", "schema": { "type": "integer" } }, { "name": "asset_gaids[]", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "succeeded": { "type": "integer" }, "failed": { "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "errors": { "anyOf": [ { "type": "array", "prefixItems": [ { "type": "object", "properties": { "id": { "type": "string" }, "error": { "type": "string" } }, "required": [ "id", "error" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false }, { "type": "string" } ] } }, "required": [ "message", "succeeded", "failed", "errors" ] } } } }, "403": { "description": "Token does not have the required abilities: collections:write", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/consents\/me": { "get": { "operationId": "v1.consents.me", "summary": "Return the authenticated user's own pending + accepted consents", "tags": [ "Consent" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user_id": { "type": "integer" }, "pending": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "version": { "type": "string" }, "content": { "type": "string" }, "language_code": { "type": "string" }, "requires_acceptance": { "type": "string" } }, "required": [ "id", "type", "title", "version", "content", "language_code", "requires_acceptance" ] } }, "accepted_by_type": { "type": "string" } }, "required": [ "user_id", "pending", "accepted_by_type" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "description": "Token does not have the required abilities: consents:read", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } } } } }, "\/consents\/users\/{user}": { "get": { "operationId": "v1.consents.user-status", "summary": "Return consent status for a given user (by id)", "tags": [ "Consent" ], "parameters": [ { "name": "user", "in": "path", "required": true, "description": "The user ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "user_id": { "type": "integer" }, "pending": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "version": { "type": "string" }, "content": { "type": "string" }, "language_code": { "type": "string" }, "requires_acceptance": { "type": "string" } }, "required": [ "id", "type", "title", "version", "content", "language_code", "requires_acceptance" ] } }, "accepted_by_type": { "type": "string" } }, "required": [ "user_id", "pending", "accepted_by_type" ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "description": "Token does not have the required abilities: consents:read", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } } } } }, "\/consents\/users\/{user}\/history": { "get": { "operationId": "v1.consents.user-history", "summary": "Return the raw consent history for a given user (append-only log)", "tags": [ "Consent" ], "parameters": [ { "name": "user", "in": "path", "required": true, "description": "The user ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" }, "meta": { "type": "object", "properties": { "current_page": { "type": "string" }, "per_page": { "type": "string" }, "total": { "type": "string" } }, "required": [ "current_page", "per_page", "total" ] } }, "required": [ "data", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "description": "Token does not have the required abilities: consents:read", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } } } } }, "\/metadata\/definitions": { "get": { "operationId": "v1.metadata.definitions", "summary": "List metadata definitions, optionally filtered by asset class", "tags": [ "Metadata" ], "parameters": [ { "name": "asset_class_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `MetadataDefinitionResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/MetadataDefinitionResource" }, { "type": "object", "required": [ "vocabulary" ] } ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "description": "Token does not have the required abilities: metadata:read", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } } } } }, "\/metadata\/vocabularies": { "get": { "operationId": "v1.metadata.vocabularies", "summary": "List vocabularies", "tags": [ "Metadata" ], "responses": { "200": { "description": "Array of `VocabularyResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/VocabularyResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "description": "Token does not have the required abilities: metadata:read", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } } } } }, "\/metadata\/vocabularies\/{vocabulary}": { "get": { "operationId": "v1.metadata.vocabulary", "summary": "Show a vocabulary with its terms", "tags": [ "Metadata" ], "parameters": [ { "name": "vocabulary", "in": "path", "required": true, "description": "The vocabulary ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`VocabularyResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/VocabularyResource" }, { "type": "object", "required": [ "root_terms" ] } ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "description": "Token does not have the required abilities: metadata:read", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } } } } }, "\/metadata\/vocabularies\/{vocabulary}\/terms": { "get": { "operationId": "v1.metadata.terms", "summary": "List terms for a vocabulary", "tags": [ "Metadata" ], "parameters": [ { "name": "vocabulary", "in": "path", "required": true, "description": "The vocabulary ID", "schema": { "type": "integer" } }, { "name": "parent_id", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Array of `VocabularyTermResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/VocabularyTermResource" }, { "type": "object", "required": [ "children" ] } ] } } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "description": "Token does not have the required abilities: metadata:read", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } } } } }, "\/metadata\/vocabularies\/{vocabulary}\/terms\/{term}": { "get": { "operationId": "v1.metadata.term", "summary": "Show a single vocabulary term", "tags": [ "Metadata" ], "parameters": [ { "name": "vocabulary", "in": "path", "required": true, "description": "The vocabulary ID", "schema": { "type": "integer" } }, { "name": "term", "in": "path", "required": true, "description": "The term ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`VocabularyTermResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/VocabularyTermResource" }, { "type": "object", "required": [ "children" ] } ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "description": "Token does not have the required abilities: metadata:read", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } } } } }, "\/operations": { "get": { "operationId": "v1.operations.index", "summary": "List operations for the authenticated user", "tags": [ "Operation" ], "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Paginated set of `OperationResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/OperationResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "v1.operations.store", "summary": "Create and dispatch a new operation", "tags": [ "Operation" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreOperationRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 201 } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/operations\/{operationId}": { "get": { "operationId": "v1.operations.show", "summary": "Show operation status and progress", "tags": [ "Operation" ], "parameters": [ { "name": "operationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`OperationResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/OperationResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/operations\/{operationId}\/cancel": { "post": { "operationId": "v1.operations.cancel", "summary": "Cancel a pending or processing operation", "tags": [ "Operation" ], "parameters": [ { "name": "operationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Operation cancelled." }, "data": { "$ref": "#\/components\/schemas\/OperationResource" } }, "required": [ "message", "data" ] } } } }, "422": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Operation cannot be cancelled in its current state." }, "status": { "$ref": "#\/components\/schemas\/ApiOperationStatus" } }, "required": [ "message", "status" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/shares": { "get": { "operationId": "v1.shares.index", "summary": "List shares for the authenticated user", "tags": [ "Share" ], "parameters": [ { "name": "shareable_type", "in": "query", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Paginated set of `ShareResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/ShareResource" }, { "type": "object", "required": [ "created_by" ] } ] } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "403": { "description": "Token does not have the required abilities: shares:read", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "v1.shares.store", "summary": "Create a new share", "tags": [ "Share" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateShareRequest" } } } }, "responses": { "201": { "description": "`ShareResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/ShareResource" }, { "type": "object", "required": [ "created_by" ] } ] } }, "required": [ "data" ] } } } }, "403": { "description": "Token does not have the required abilities: shares:manage", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/shares\/{share}": { "get": { "operationId": "v1.shares.show", "summary": "Show a single share", "tags": [ "Share" ], "parameters": [ { "name": "share", "in": "path", "required": true, "description": "The share ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`ShareResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/ShareResource" }, { "type": "object", "required": [ "created_by" ] } ] } }, "required": [ "data" ] } } } }, "403": { "description": "Token does not have the required abilities: shares:read", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "v1.shares.update", "summary": "Update a share", "tags": [ "Share" ], "parameters": [ { "name": "share", "in": "path", "required": true, "description": "The share ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateShareRequest" } } } }, "responses": { "200": { "description": "`ShareResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/ShareResource" }, { "type": "object", "required": [ "created_by" ] } ] } }, "required": [ "data" ] } } } }, "403": { "description": "Token does not have the required abilities: shares:manage", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "v1.shares.destroy", "summary": "Delete a share", "tags": [ "Share" ], "parameters": [ { "name": "share", "in": "path", "required": true, "description": "The share ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Share deleted." } }, "required": [ "message" ] } } } }, "403": { "description": "Token does not have the required abilities: shares:manage", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/shares\/{share}\/revoke": { "post": { "operationId": "v1.shares.revoke", "summary": "Revoke a share (permanently deactivate)", "tags": [ "Share" ], "parameters": [ { "name": "share", "in": "path", "required": true, "description": "The share ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`ShareResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/ShareResource" }, { "type": "object", "required": [ "created_by" ] } ] } }, "required": [ "data" ] } } } }, "403": { "description": "Token does not have the required abilities: shares:manage", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/uploads\/batches": { "post": { "operationId": "uploads.createBatch", "description": "Upload workflow:\n1. **Create a batch** (this endpoint) \u2014 returns a `batch_uuid` used in subsequent calls.\n2. **Upload files** (`POST \/api\/v1\/uploads\/batches\/{batch}\/files`) \u2014 send one file per request with optional per-file metadata.\n3. **Poll status** (`GET \/api\/v1\/uploads\/batches\/{batch}`) \u2014 check processing progress until all files reach a terminal status (`completed` or `failed`).\n\nBatch-level metadata fields (`title`, `description`, `keywords`, `creator`, `copyright`, `location`, `metadata`)\nact as defaults for every file in the batch. Per-file metadata sent during upload overrides these defaults.", "summary": "Create a new upload batch", "tags": [ "Upload" ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateUploadBatchRequest" } } } }, "responses": { "422": { "$ref": "#\/components\/responses\/ValidationException" }, "201": { "description": "`IngestionBatchResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/IngestionBatchResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "description": "Token does not have the required abilities: uploads:manage", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } } } } }, "\/uploads\/batches\/{batch}\/files": { "post": { "operationId": "uploads.uploadFile", "description": "Send the file as `multipart\/form-data`. Alongside the binary `file` field, you may include\nper-file metadata fields that override the batch defaults set during batch creation.\n\nBecause multipart forms cannot nest arrays, `keywords` should be sent as a JSON array string\n(e.g. `[\"landscape\",\"sunset\"]`) or comma-separated (e.g. `landscape,sunset`).\nThe `metadata` field should be a JSON object string (e.g. `{\"product_sku\":\"ABC123\"}`).\n\n**Metadata precedence** (highest to lowest):\n1. Per-file metadata (this request)\n2. Batch defaults (`shared_metadata` from batch creation)\n3. Extracted file metadata (EXIF, XMP, etc.)", "summary": "Upload a file to an existing batch", "tags": [ "Upload" ], "parameters": [ { "name": "batch", "in": "path", "required": true, "description": "The batch ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart\/form-data": { "schema": { "$ref": "#\/components\/schemas\/UploadFileRequest" } } } }, "responses": { "422": { "$ref": "#\/components\/responses\/ValidationException" }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "File uploaded and queued for processing." }, "ingestion_job_id": { "type": "string" }, "batch_uuid": { "type": "string" } }, "required": [ "message", "ingestion_job_id", "batch_uuid" ] } } } }, "403": { "description": "Token does not have the required abilities: uploads:manage", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/uploads\/batches\/{batch}": { "get": { "operationId": "uploads.batchStatus", "description": "Poll this endpoint to track processing progress. Each file in the batch transitions through\nstatuses: `uploading` \u2192 `scanning` \u2192 `storing` \u2192 `processing_metadata` \u2192 `processing_ai` \u2192 `finalizing` \u2192 `completed`.\nA file may also reach `failed` at any stage. The batch is finished when all files are `completed` or `failed`.", "summary": "Get the status of an upload batch", "tags": [ "Upload" ], "parameters": [ { "name": "batch", "in": "path", "required": true, "description": "The batch ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`IngestionBatchResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#\/components\/schemas\/IngestionBatchResource" }, { "type": "object", "required": [ "user" ] } ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "description": "Token does not have the required abilities: uploads:manage", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "required_abilities": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "required_abilities" ] } } } } } } }, "\/webhooks": { "get": { "operationId": "v1.webhooks.index", "summary": "List webhook endpoints for the authenticated user", "tags": [ "Webhook" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/WebhookEndpoint" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "v1.webhooks.store", "description": "Returns the webhook endpoint with its secret. The secret is only shown once at creation time.", "summary": "Create a new webhook endpoint", "tags": [ "Webhook" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreWebhookRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 201 } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/webhooks\/{webhook}": { "get": { "operationId": "v1.webhooks.show", "summary": "Show a webhook endpoint", "tags": [ "Webhook" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The webhook ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": {} }, "is_active": { "type": "boolean" }, "failure_count": { "type": "integer" }, "last_delivery_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "description", "events", "is_active", "failure_count", "last_delivery_at", "created_at", "updated_at" ] } }, "required": [ "data" ] } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "" ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "v1.webhooks.update", "summary": "Update a webhook endpoint", "tags": [ "Webhook" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The webhook ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateWebhookRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": {} }, "is_active": { "type": "boolean" }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "description", "events", "is_active", "updated_at" ] } }, "required": [ "data" ] } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "" ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } }, "delete": { "operationId": "v1.webhooks.destroy", "summary": "Delete a webhook endpoint", "tags": [ "Webhook" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The webhook ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Webhook deleted." } }, "required": [ "message" ] } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "" ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/webhooks\/{webhook}\/test": { "post": { "operationId": "v1.webhooks.test", "summary": "Send a test event to the webhook endpoint", "tags": [ "Webhook" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The webhook ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Test webhook dispatched." } }, "required": [ "message" ] } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "" ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/webhooks\/{webhook}\/deliveries": { "get": { "operationId": "v1.webhooks.deliveries", "summary": "List recent deliveries for a webhook endpoint", "tags": [ "Webhook" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The webhook ID", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/WebhookDelivery" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "" ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/webhooks\/{webhook}\/rotate-secret": { "post": { "operationId": "v1.webhooks.rotate-secret", "description": "Generates a new secret and allows a 24-hour grace period for the old one.", "summary": "Rotate the webhook secret", "tags": [ "Webhook" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The webhook ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 200 } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "" ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } }, "schemas": { "ApiOperationStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "partially_completed", "cancelled" ], "title": "ApiOperationStatus" }, "ApiOperationType": { "type": "string", "enum": [ "asset_upload_batch", "asset_bulk_update", "asset_bulk_delete", "ai_analyze", "export_download" ], "title": "ApiOperationType" }, "AssetCollection": { "type": "array", "items": { "$ref": "#\/components\/schemas\/AssetResource" }, "title": "AssetCollection" }, "AssetEmbedResource": { "type": "object", "properties": { "token": { "type": "string" }, "asset_gaid": { "type": "string" }, "embed_url": { "type": "string" }, "iframe_html": { "type": "string" }, "responsive_html": { "type": [ "string", "null" ] }, "width": { "type": "string" }, "height": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] }, "allowed_domains": { "type": [ "string", "null" ] }, "options": { "type": "string" } }, "required": [ "token", "asset_gaid", "embed_url", "iframe_html", "responsive_html", "width", "height", "expires_at", "allowed_domains", "options" ], "title": "AssetEmbedResource" }, "AssetResolution": { "type": "string", "description": "Asset Resolution Enum Defines standardized asset resolutions for image processing, thumbnails, and downloads. This enum provides a centralized configuration for all asset resolution variants used throughout the application, ensuring consistency between backend processing and frontend display. The enum supports multiple resolution tiers from mini thumbnails (128px) to ultra-large previews (5120px), plus the original file. Each resolution has associated metadata for pixel dimensions, quality settings, and UI presentation.\n| |\n|---|\n| `original` Original file resolution - no conversion applied Used for full-quality downloads and when no processing is needed Represents the source file as uploaded, with no size restrictions |\n| `w_5120` Ultra Large thumbnail (5120\u00d75120px) Maximum quality variant for true 5K displays and wide zoom canvases Generated lazily on-demand to avoid storage\/processing cost during ingestion |\n| `w_4096` Ultra Large thumbnail (4096\u00d74096px) High-quality variant for 4K-class displays and detailed zoom views Generated lazily on-demand to avoid storage\/processing cost during ingestion |\n| `w_2048` Extra Large thumbnail (2048\u00d72048px) Highest quality thumbnail for detailed viewing and large displays Generated lazily on-demand to optimize storage and processing |\n| `w_1024` Large thumbnail (1024\u00d71024px) High-quality preview for galleries and detailed asset viewing Good balance between quality and file size for web display |\n| `w_512` Medium thumbnail (512\u00d7512px) Standard preview size for asset listings and grid views Commonly used as default preview throughout the application |\n| `w_256` Small thumbnail (256\u00d7256px) Compact preview for compact displays and mobile interfaces Suitable for asset selection and overview displays |\n| `w_128` Thumbnail (128\u00d7128px) Small preview for lists and compact asset representations Optimized for performance in large asset collections |", "enum": [ "original", "w_5120", "w_4096", "w_2048", "w_1024", "w_512", "w_256", "w_128" ], "title": "AssetResolution" }, "AssetResource": { "type": "object", "properties": { "gaid": { "type": "string" }, "original_filename": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "mime_type": { "type": "string" }, "type": { "type": [ "string", "null" ] }, "extension": { "type": "string" }, "asset_class": { "type": "object", "description": "Asset class", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" } }, "required": [ "id", "name", "code" ] }, "file_size": { "type": "integer", "description": "Technical specifications" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "aspect_ratio": { "type": [ "number", "null" ] }, "duration": { "type": "integer" }, "dpi": { "type": "number" }, "color_space": { "type": [ "string", "null" ] }, "pages": { "type": "integer" }, "is_animated": { "type": "string" }, "preview_skipped": { "type": "boolean" }, "preview_skipped_reason": { "type": [ "string", "null" ] }, "creator": { "type": "string", "description": "Content fields" }, "copyright": { "type": "string" }, "keywords": { "type": [ "array", "null" ], "items": {} }, "capture_date": { "type": [ "string", "null" ] }, "gps_latitude": { "type": "string", "description": "Geographic" }, "gps_longitude": { "type": "string" }, "location": { "type": "string" }, "ai_caption": { "type": "string", "description": "AI-generated content" }, "ai_tags": { "type": "array", "items": {} }, "ocr_text": { "type": "string" }, "dominant_color_foreground": { "type": "string" }, "dominant_color_background": { "type": "string" }, "color_palette": { "type": "array", "items": {} }, "focus_point": { "type": "array", "items": {} }, "blur_hash": { "type": "string" }, "ingestion_status": { "type": "string", "description": "Processing" }, "ingested_at": { "type": [ "string", "null" ] }, "metadata_complete": { "type": "boolean" }, "missing_required_fields": { "type": "array", "items": {} }, "workflow_status": { "type": "object", "description": "Workflow", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "progress": { "type": "integer" } }, "required": [ "code", "label", "progress" ] }, "rights": { "type": "object", "description": "Rights summary", "properties": { "policy_id": { "type": "integer" }, "policy_title": { "type": "string" }, "policy_type": { "type": "string" }, "is_active": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "expires_at": { "type": [ "string", "null" ] } }, "required": [ "policy_id", "policy_title", "policy_type", "is_active", "is_expired", "expires_at" ] }, "metadata": { "type": "array", "description": "Metadata (custom fields)", "items": {} }, "collections": { "type": "array", "description": "Collections", "items": { "$ref": "#\/components\/schemas\/CollectionResource" } }, "owner": { "anyOf": [ { "description": "Users", "$ref": "#\/components\/schemas\/UserResource" }, { "type": "null" } ] }, "created_by": { "$ref": "#\/components\/schemas\/UserResource" }, "updated_by": { "$ref": "#\/components\/schemas\/UserResource" }, "media_urls": { "type": "object", "description": "Full media URL set: thumbnails + base preview + original +\nHLS master + converted PDF + signed download. Each individual\nURL is null when not applicable for the asset's MIME type or\ncurrent processing state, so the response shape is stable\nacross asset types.", "properties": { "thumbnails": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "base_preview": { "type": [ "string", "null" ] }, "original": { "type": [ "string", "null" ] }, "hls_master": { "type": [ "string", "null" ] }, "converted_pdf": { "type": [ "string", "null" ] }, "download": { "type": [ "string", "null" ] } }, "required": [ "thumbnails", "base_preview", "original", "hls_master", "converted_pdf", "download" ] }, "created_at": { "type": [ "string", "null" ], "description": "Timestamps" }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "gaid", "original_filename", "title", "description", "mime_type", "type", "extension", "file_size", "width", "height", "aspect_ratio", "duration", "dpi", "color_space", "pages", "is_animated", "preview_skipped", "preview_skipped_reason", "creator", "copyright", "keywords", "capture_date", "gps_latitude", "gps_longitude", "location", "ai_caption", "ai_tags", "ocr_text", "dominant_color_foreground", "dominant_color_background", "color_palette", "focus_point", "blur_hash", "ingestion_status", "ingested_at", "metadata_complete", "missing_required_fields", "media_urls", "created_at", "updated_at" ], "title": "AssetResource" }, "CollectionCollection": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/CollectionResource" }, { "type": "object", "required": [ "created_by", "updated_by" ] } ] }, "title": "CollectionCollection" }, "CollectionResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "is_active": { "type": "boolean" }, "is_public": { "type": "boolean" }, "sort_order": { "type": "integer" }, "parent_id": { "type": [ "integer", "null" ] }, "collection_type": { "type": "object", "description": "Collection type", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" } }, "required": [ "id", "name", "code" ] }, "cover_asset_id": { "type": [ "integer", "null" ], "description": "Cover asset" }, "assets_count": { "type": "string", "description": "Counts" }, "children_count": { "type": "string" }, "parent": { "anyOf": [ { "description": "Hierarchy", "$ref": "#\/components\/schemas\/CollectionResource" }, { "type": "null" } ] }, "children": { "type": "array", "items": { "$ref": "#\/components\/schemas\/CollectionResource" } }, "created_by": { "description": "Users", "$ref": "#\/components\/schemas\/UserResource" }, "updated_by": { "$ref": "#\/components\/schemas\/UserResource" }, "created_at": { "type": [ "string", "null" ], "description": "Timestamps" }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "description", "is_active", "is_public", "sort_order", "parent_id", "cover_asset_id", "created_at", "updated_at" ], "title": "CollectionResource" }, "CreateApiTokenRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "abilities": { "type": "array", "items": { "type": "string", "enum": [ "assets:read", "assets:write", "assets:delete", "assets:download", "collections:read", "collections:write", "collections:delete", "uploads:manage", "metadata:read", "metadata:write", "shares:read", "shares:manage", "analytics:read", "consents:read", "admin:full" ] }, "minItems": 1 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "name", "abilities" ], "title": "CreateApiTokenRequest" }, "CreateAssetEmbedRequest": { "type": "object", "description": "Validation rules for generating an embed code for a video asset.\n\nAll fields are optional \u2014 calling the endpoint with an empty body\nyields the default 16:9 responsive player with controls.", "properties": { "width": { "type": [ "integer", "null" ], "description": "Player size for the non-responsive iframe snippet.", "minimum": 160, "maximum": 3840 }, "height": { "type": [ "integer", "null" ], "minimum": 90, "maximum": 2160 }, "responsive": { "type": [ "boolean", "null" ], "description": "Generates an extra responsive_html string with an aspect-ratio wrapper." }, "autoplay": { "type": [ "boolean", "null" ], "description": "Player option flags forwarded to the embed page as query params." }, "muted": { "type": [ "boolean", "null" ] }, "loop": { "type": [ "boolean", "null" ] }, "controls": { "type": [ "boolean", "null" ] }, "start": { "type": [ "integer", "null" ], "minimum": 0 }, "allowed_domains": { "type": [ "array", "null" ], "description": "CSP frame-ancestors allowlist. Null\/empty = open to any origin.", "items": { "type": "string", "maxLength": 253 } }, "force_new": { "type": [ "boolean", "null" ], "description": "If true, force a brand-new share even when one already exists." } }, "title": "CreateAssetEmbedRequest" }, "CreateCollectionRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "collection_type_id": { "type": "integer" }, "parent_id": { "type": [ "integer", "null" ] }, "is_active": { "type": [ "boolean", "null" ] }, "is_public": { "type": [ "boolean", "null" ] }, "cover_asset_id": { "type": [ "integer", "null" ] } }, "required": [ "name", "collection_type_id" ], "title": "CreateCollectionRequest" }, "CreateShareRequest": { "type": "object", "properties": { "shareable_type": { "type": "string", "enum": [ "collection", "asset", "selection" ] }, "shareable_id": { "type": [ "integer", "null" ] }, "asset_ids": { "type": [ "array", "null" ], "items": { "type": "integer" }, "minItems": 1 }, "access_type": { "type": "string", "enum": [ "public", "email_restricted", "password_protected", "private" ] }, "allowed_emails": { "type": [ "array", "null" ], "items": { "type": "string", "format": "email" } }, "allowed_domains": { "type": [ "array", "null" ], "items": { "type": "string" } }, "password": { "type": [ "string", "null" ], "minLength": 6 }, "permissions": { "type": "object", "properties": { "view": { "type": "boolean" }, "download": { "type": "boolean" } } }, "download_resolution": { "anyOf": [ { "$ref": "#\/components\/schemas\/AssetResolution" }, { "type": "null" } ] }, "watermark_id": { "type": [ "integer", "null" ] }, "starts_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "shareable_type", "access_type" ], "title": "CreateShareRequest" }, "CreateUploadBatchRequest": { "type": "object", "properties": { "batch_name": { "type": [ "string", "null" ], "description": "Human-readable name for this batch. Defaults to \"API Upload\".", "maxLength": 255 }, "asset_class_id": { "type": [ "integer", "null" ], "description": "Asset class to assign to all files in this batch (overridden by per-file values)." }, "collection_id": { "type": [ "integer", "null" ], "description": "Collection to add all files to after processing (overridden by per-file values)." }, "target_workflow_status": { "type": [ "string", "null" ], "description": "Workflow status to apply after processing (e.g. \"approved\")." }, "title": { "type": [ "string", "null" ], "description": "Default title for all files in the batch. Overridden by per-file title or extracted EXIF title.", "maxLength": 500 }, "description": { "type": [ "string", "null" ], "description": "Default description for all files in the batch.", "maxLength": 5000 }, "keywords": { "type": [ "array", "null" ], "description": "Default keywords for all files. Each keyword is a string.", "items": { "type": "string", "maxLength": 255 } }, "creator": { "type": [ "string", "null" ], "description": "Default creator\/author for all files.", "maxLength": 255 }, "copyright": { "type": [ "string", "null" ], "description": "Default copyright notice for all files.", "maxLength": 1000 }, "location": { "type": [ "string", "null" ], "description": "Default location for all files.", "maxLength": 500 }, "metadata": { "type": [ "array", "null" ], "description": "Arbitrary key-value metadata applied to all files. Per-file metadata overrides these values.", "items": { "type": [ "string", "null" ] } } }, "title": "CreateUploadBatchRequest" }, "IngestionBatchResource": { "type": "object", "properties": { "id": { "type": "string" }, "batch_uuid": { "type": "string" }, "batch_name": { "type": "string" }, "status": { "type": "string" }, "total_files": { "type": "integer" }, "processed_files": { "type": "integer" }, "successful_files": { "type": "string" }, "failed_files": { "type": "integer" }, "is_in_progress": { "type": "boolean" }, "is_completed": { "type": "boolean" }, "has_failed": { "type": "boolean" }, "started_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "failed_at": { "type": [ "string", "null" ] }, "error_message": { "type": "string" }, "user": { "anyOf": [ { "$ref": "#\/components\/schemas\/UserResource" }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "batch_uuid", "batch_name", "status", "total_files", "processed_files", "successful_files", "failed_files", "is_in_progress", "is_completed", "has_failed", "started_at", "completed_at", "failed_at", "error_message", "created_at", "updated_at" ], "title": "IngestionBatchResource" }, "ManageCollectionAssetsRequest": { "type": "object", "properties": { "asset_gaids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 500 } }, "required": [ "asset_gaids" ], "title": "ManageCollectionAssetsRequest" }, "MetadataDefinitionResource": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "is_multilingual": { "type": "boolean" }, "is_required": { "type": "boolean" }, "is_sensitive": { "type": "boolean" }, "allow_multiple": { "type": "boolean" }, "hide_when_empty": { "type": "boolean" }, "default_value": { "type": "string" }, "help_text": { "type": "string" }, "field_hint": { "type": "string" }, "asset_class_id": { "type": "integer" }, "vocabulary_id": { "type": "integer" }, "parent_field_id": { "type": [ "integer", "null" ] }, "parent_field_key": { "type": [ "string", "null" ] }, "vocabulary": { "$ref": "#\/components\/schemas\/VocabularyResource" } }, "required": [ "id", "key", "label", "type", "is_multilingual", "is_required", "is_sensitive", "allow_multiple", "hide_when_empty", "default_value", "help_text", "field_hint", "asset_class_id", "vocabulary_id", "parent_field_id", "parent_field_key" ], "title": "MetadataDefinitionResource" }, "OperationResource": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "$ref": "#\/components\/schemas\/ApiOperationType" }, "status": { "$ref": "#\/components\/schemas\/ApiOperationStatus" }, "progress_percentage": { "type": "integer" }, "current_stage": { "type": [ "string", "null" ] }, "input_params": { "type": [ "array", "null" ], "items": {} }, "result": { "type": [ "array", "null" ], "items": {} }, "error": { "type": [ "array", "null" ], "items": {} }, "logs": { "type": "array", "items": {} }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "status", "progress_percentage", "current_stage", "input_params", "result", "error", "created_at", "updated_at" ], "title": "OperationResource" }, "ShareResource": { "type": "object", "properties": { "id": { "type": "string" }, "share_token": { "type": "string" }, "vanity_url": { "type": "string" }, "shareable_type": { "type": "string" }, "shareable_id": { "type": "integer" }, "access_type": { "type": "string" }, "allowed_emails": { "type": [ "array", "null" ], "items": {} }, "allowed_domains": { "type": "array", "items": {} }, "has_password": { "type": "boolean" }, "permissions": { "type": "array", "items": {} }, "download_resolution": { "type": "string" }, "watermark_required": { "type": "boolean" }, "watermark_id": { "type": [ "integer", "null" ] }, "is_active": { "type": "boolean" }, "status": { "type": "string" }, "starts_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "asset_ids": { "type": "array", "items": {} }, "created_by": { "$ref": "#\/components\/schemas\/UserResource" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "share_token", "vanity_url", "shareable_type", "shareable_id", "access_type", "allowed_emails", "allowed_domains", "has_password", "permissions", "download_resolution", "watermark_required", "watermark_id", "is_active", "status", "starts_at", "expires_at", "revoked_at", "asset_ids", "created_at", "updated_at" ], "title": "ShareResource" }, "StoreOperationRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "asset_upload_batch", "asset_bulk_update" ] }, "params": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "type", "params" ], "title": "StoreOperationRequest" }, "StoreWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "asset.created", "asset.updated", "asset.deleted", "asset.downloaded", "collection.created", "collection.updated", "collection.deleted", "collection.assets_added", "collection.assets_removed", "share.created", "share.accessed", "upload.batch_completed", "upload.batch_failed", "workflow.transitioned" ] }, "minItems": 1 } }, "required": [ "url", "events" ], "title": "StoreWebhookRequest" }, "UpdateAssetRequest": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "ai_caption": { "type": [ "string", "null" ], "maxLength": 5000 }, "ai_tags": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 100 } }, "keywords": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 100 } }, "ocr_text": { "type": [ "string", "null" ], "maxLength": 5000 }, "metadata": { "type": "array", "items": { "type": "string" } }, "workflow_status": { "type": "string" }, "asset_class_id": { "type": "integer" } }, "title": "UpdateAssetRequest" }, "UpdateCollectionRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "is_active": { "type": "boolean" }, "is_public": { "type": "boolean" }, "parent_id": { "type": [ "integer", "null" ] }, "cover_asset_id": { "type": [ "integer", "null" ] } }, "title": "UpdateCollectionRequest" }, "UpdateShareRequest": { "type": "object", "properties": { "access_type": { "type": "string", "enum": [ "public", "email_restricted", "password_protected", "private" ] }, "allowed_emails": { "type": [ "array", "null" ], "items": { "type": "string", "format": "email" } }, "allowed_domains": { "type": [ "array", "null" ], "items": { "type": "string" } }, "password": { "type": [ "string", "null" ], "minLength": 6 }, "permissions": { "type": "object", "properties": { "view": { "type": "boolean" }, "download": { "type": "boolean" } } }, "download_resolution": { "anyOf": [ { "$ref": "#\/components\/schemas\/AssetResolution" }, { "type": "null" } ] }, "watermark_id": { "type": [ "integer", "null" ] }, "starts_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_active": { "type": "boolean" } }, "title": "UpdateShareRequest" }, "UpdateWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "asset.created", "asset.updated", "asset.deleted", "asset.downloaded", "collection.created", "collection.updated", "collection.deleted", "collection.assets_added", "collection.assets_removed", "share.created", "share.accessed", "upload.batch_completed", "upload.batch_failed", "workflow.transitioned" ] }, "minItems": 1 }, "is_active": { "type": "boolean" } }, "title": "UpdateWebhookRequest" }, "UploadFileRequest": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "contentMediaType": "application\/octet-stream", "description": "The binary file to upload." }, "title": { "type": [ "string", "null" ], "description": "Title for this specific file. Overrides batch default and extracted EXIF title.", "maxLength": 500 }, "description": { "type": [ "string", "null" ], "description": "Description for this specific file. Overrides batch default.", "maxLength": 5000 }, "keywords": { "type": [ "string", "null" ], "description": "Keywords as a JSON array string (e.g. '[\"landscape\",\"sunset\"]') or comma-separated (e.g. \"landscape,sunset\"). Multipart forms cannot nest arrays." }, "creator": { "type": [ "string", "null" ], "description": "Creator\/author for this specific file. Overrides batch default and extracted EXIF creator.", "maxLength": 255 }, "copyright": { "type": [ "string", "null" ], "description": "Copyright notice for this specific file. Overrides batch default.", "maxLength": 1000 }, "location": { "type": [ "string", "null" ], "description": "Location for this specific file. Overrides batch default.", "maxLength": 500 }, "asset_class_id": { "type": [ "integer", "null" ], "description": "Asset class for this specific file. Overrides batch default." }, "collection_id": { "type": [ "integer", "null" ], "description": "Collection to add this specific file to. Overrides batch default." }, "metadata": { "type": [ "string", "null" ], "description": "Arbitrary key-value metadata as a JSON string (e.g. '{\"product_sku\":\"ABC123\"}'). Overrides batch metadata keys." } }, "required": [ "file" ], "title": "UploadFileRequest" }, "UserResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "created_at" ], "title": "UserResource" }, "VocabularyResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "is_tree": { "type": "boolean" }, "sort_order": { "type": "string" }, "terms": { "type": "array", "items": { "$ref": "#\/components\/schemas\/VocabularyTermResource" } }, "root_terms": { "type": "array", "items": { "$ref": "#\/components\/schemas\/VocabularyTermResource" } } }, "required": [ "id", "name", "code", "is_tree", "sort_order" ], "title": "VocabularyResource" }, "VocabularyTermResource": { "type": "object", "properties": { "id": { "type": "string" }, "vocabulary_id": { "type": "integer" }, "parent_id": { "type": [ "integer", "null" ] }, "code": { "type": "string" }, "label": { "type": "string" }, "labels": { "type": "object", "additionalProperties": { "type": "string" } }, "sort_order": { "type": "integer" }, "children": { "type": "array", "items": { "$ref": "#\/components\/schemas\/VocabularyTermResource" } } }, "required": [ "id", "vocabulary_id", "parent_id", "code", "label", "labels", "sort_order" ], "title": "VocabularyTermResource" }, "WebhookDelivery": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false, "title": "WebhookDelivery" }, "WebhookEndpoint": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false, "title": "WebhookEndpoint" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "AuthorizationException": { "description": "Authorization error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }