{ "schemes": [ "https" ], "swagger": "2.0", "info": { "description": "Digital assets, folders, and renditions.", "title": "DAM API", "contact": {}, "version": "1.0" }, "basePath": "/v1", "paths": { "/assets/notify-upload": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Notify the service that an asset has been successfully uploaded to S3; creates the asset record", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Assets" ], "summary": "Notify asset upload completion", "parameters": [ { "description": "Upload notification payload", "name": "body", "in": "body", "required": true, "schema": { "type": "object", "properties": { "folder_id": { "type": "string" }, "key": { "type": "string" } } } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/handler.swaggerAssetDetailsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } } } } }, "/assets/upload-url": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Generate a presigned S3 URL for uploading an asset directly to object storage", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Assets" ], "summary": "Get presigned upload URL", "parameters": [ { "type": "string", "description": "File name", "name": "file_name", "in": "query", "required": true }, { "type": "string", "description": "MIME content type (e.g. application/pdf)", "name": "content_type", "in": "query", "required": true }, { "type": "integer", "description": "File size in bytes", "name": "size", "in": "query", "required": true }, { "type": "string", "description": "Destination folder ID", "name": "folder_id", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.swaggerAssetUploadURLResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } } } } }, "/assets/{id}": { "delete": { "security": [ { "BearerAuth": [] } ], "description": "Soft delete an asset", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Assets" ], "summary": "Delete an asset", "parameters": [ { "type": "string", "description": "Asset ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.swaggerSuccessResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Update an asset's name", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Assets" ], "summary": "Update an asset", "parameters": [ { "type": "string", "description": "Asset ID", "name": "id", "in": "path", "required": true }, { "description": "Asset update payload", "name": "body", "in": "body", "required": true, "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.swaggerAssetDetailsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } } } } }, "/folders": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve a paginated list of folders, optionally filtered by parent", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Folders" ], "summary": "Get list of folders", "parameters": [ { "type": "string", "description": "Parent folder ID", "name": "parent_id", "in": "query" }, { "type": "integer", "default": 1, "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "default": 10, "description": "Page size", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.swaggerFolderListResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } } } }, "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a new folder under an optional parent folder, or seed from a category", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Folders" ], "summary": "Create a new folder", "parameters": [ { "description": "Folder creation payload", "name": "body", "in": "body", "required": true, "schema": { "type": "object", "properties": { "category_id": { "type": "string" }, "name": { "type": "string" }, "parent_id": { "type": "string" } } } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/handler.swaggerFolderDetailsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } } } } }, "/folders/initialize": { "post": { "security": [ { "BearerAuth": [] } ], "description": "Create a root folder and folder structure based on a category tree for the tenant", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Folders" ], "summary": "Initialize folders from category tree", "parameters": [ { "description": "Optional category ID to seed folder structure from", "name": "body", "in": "body", "schema": { "type": "object", "properties": { "category_id": { "type": "string" } } } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/handler.swaggerFolderDetailsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } } } } }, "/folders/{id}": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve detailed information about a specific folder including child folders and assets", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Folders" ], "summary": "Get folder details", "parameters": [ { "type": "string", "description": "Folder ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.swaggerFolderDetailsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } } } }, "delete": { "security": [ { "BearerAuth": [] } ], "description": "Soft delete a folder and its contents", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Folders" ], "summary": "Delete a folder", "parameters": [ { "type": "string", "description": "Folder ID", "name": "id", "in": "path", "required": true }, { "type": "boolean", "description": "Force delete even if folder has children", "name": "force", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.swaggerSuccessResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } } } }, "patch": { "security": [ { "BearerAuth": [] } ], "description": "Update an existing folder's name", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Folders" ], "summary": "Update a folder", "parameters": [ { "type": "string", "description": "Folder ID", "name": "id", "in": "path", "required": true }, { "description": "Folder update payload", "name": "body", "in": "body", "required": true, "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.swaggerFolderDetailsResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } } } } }, "/folders/{id}/breadcrumb": { "get": { "security": [ { "BearerAuth": [] } ], "description": "Retrieve the breadcrumb trail (ancestor path) for a specific folder", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Folders" ], "summary": "Get folder breadcrumb", "parameters": [ { "type": "string", "description": "Folder ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.swaggerFolderBreadcrumbResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/handler.swaggerErrorResponse" } } } } }, "/health": { "get": { "description": "Check if the service is healthy", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Health" ], "summary": "Health check", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/handler.swaggerSuccessResponse" } } } } } }, "definitions": { "handler.swaggerAssetDetailsResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.AssetDetails" }, "message": { "type": "string" }, "success": { "type": "boolean" }, "trace_id": { "type": "string" } } }, "handler.swaggerAssetUploadURLResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.AssetUploadURLResponse" }, "message": { "type": "string" }, "success": { "type": "boolean" }, "trace_id": { "type": "string" } } }, "handler.swaggerErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/definitions/model.ErrorInfo" } }, "message": { "type": "string" }, "success": { "type": "boolean" }, "trace_id": { "type": "string" } } }, "handler.swaggerFolderBreadcrumbResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.FolderBreadcrumbResponse" }, "message": { "type": "string" }, "success": { "type": "boolean" }, "trace_id": { "type": "string" } } }, "handler.swaggerFolderDetailsResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/model.FolderDetails" }, "message": { "type": "string" }, "success": { "type": "boolean" }, "trace_id": { "type": "string" } } }, "handler.swaggerFolderListData": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/model.FolderListItem" } }, "pagination": { "$ref": "#/definitions/model.PaginationInfo" } } }, "handler.swaggerFolderListResponse": { "type": "object", "properties": { "data": { "$ref": "#/definitions/handler.swaggerFolderListData" }, "message": { "type": "string" }, "success": { "type": "boolean" }, "trace_id": { "type": "string" } } }, "handler.swaggerSuccessResponse": { "type": "object", "properties": { "message": { "type": "string" }, "success": { "type": "boolean" } } }, "model.ActorInfo": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "example": "John Doe" }, "type": { "type": "string", "example": "user" } } }, "model.AssetDetails": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-03-17T10:00:00Z" }, "created_by": { "$ref": "#/definitions/model.ActorInfo" }, "description": { "type": "string", "example": "A sample PDF document" }, "file_path": { "type": "string", "example": "assets/documents/document.pdf" }, "file_size": { "type": "integer", "example": 102400 }, "file_type": { "type": "string", "example": "application/pdf" }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "is_deleted": { "type": "boolean", "example": false }, "modified_at": { "type": "string", "example": "2026-03-17T12:00:00Z" }, "modified_by": { "$ref": "#/definitions/model.ActorInfo" }, "name": { "type": "string", "example": "document.pdf" }, "status": { "type": "string", "example": "uploaded" }, "tenant_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440001" }, "version": { "$ref": "#/definitions/model.AssetVersionDetails" } } }, "model.AssetUploadURLResponse": { "type": "object", "properties": { "content_type": { "type": "string", "example": "application/pdf" }, "expires_in": { "type": "integer", "example": 3600 }, "folder_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "key": { "type": "string", "example": "assets/documents/document.pdf" }, "upload_url": { "type": "string", "example": "https://s3.amazonaws.com/bucket/key?signature=..." } } }, "model.AssetVersionDetails": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-03-17T10:00:00Z" }, "file_path": { "type": "string", "example": "assets/documents/document.pdf" }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "rendition_paths": { "type": "string" }, "version_label": { "type": "string", "example": "v1.0" }, "version_notes": { "type": "string", "example": "Initial version" }, "version_number": { "type": "integer", "example": 1 } } }, "model.BreadcrumbItem": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "example": "Assets" } } }, "model.ErrorInfo": { "type": "object", "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "field is required" } } }, "model.FolderAssetItem": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2026-03-17T10:00:00Z" }, "created_by": { "$ref": "#/definitions/model.ActorInfo" }, "file_size": { "type": "integer", "example": 102400 }, "file_type": { "type": "string", "example": "application/pdf" }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "example": "document.pdf" }, "presigned_url": { "type": "string" }, "status": { "type": "string", "example": "uploaded" } } }, "model.FolderBreadcrumbResponse": { "type": "object", "properties": { "breadcrumb": { "type": "array", "items": { "$ref": "#/definitions/model.BreadcrumbItem" } } } }, "model.FolderDetails": { "type": "object", "properties": { "assets": { "type": "array", "items": { "$ref": "#/definitions/model.FolderAssetItem" } }, "child_asset_count": { "type": "integer", "example": 5 }, "child_folder_count": { "type": "integer", "example": 3 }, "created_at": { "type": "string", "example": "2026-03-17T10:00:00Z" }, "created_by": { "$ref": "#/definitions/model.ActorInfo" }, "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "level": { "type": "integer", "example": 0 }, "modified_at": { "type": "string", "example": "2026-03-17T12:00:00Z" }, "modified_by": { "$ref": "#/definitions/model.ActorInfo" }, "name": { "type": "string", "example": "Assets" }, "parent_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440001" }, "path_ids": { "type": "array", "items": { "type": "string" } }, "sub_folders": { "type": "array", "items": { "$ref": "#/definitions/model.FolderListItem" } } } }, "model.FolderListItem": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "example": "Assets" }, "parent_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440001" } } }, "model.PaginationInfo": { "type": "object", "properties": { "has_next": { "type": "boolean", "example": true }, "page": { "type": "integer", "example": 1 }, "page_size": { "type": "integer", "example": 10 }, "total_pages": { "type": "integer", "example": 5 }, "total_records": { "type": "integer", "example": 50 } } } }, "securityDefinitions": { "BearerAuth": { "type": "apiKey", "name": "Authorization", "in": "header" } }, "host": "api.catazenta.com" }