{ "openapi": "3.1.0", "info": { "title": "Aspect API", "description": "Manage and search media in Aspect.", "version": "1.0.0" }, "servers": [ { "url": "https://api.aspect.inc" } ], "paths": { "/users/me": { "get": { "tags": [ "Users" ], "summary": "Get Current User", "description": "Get the current authenticated user", "operationId": "get_current_user", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } } } } }, "/workspaces": { "get": { "tags": [ "Workspaces" ], "summary": "List Workspaces", "description": "List all workspaces the user has access to", "operationId": "list_workspaces", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/WorkspaceResponse" }, "type": "array", "title": "Response List Workspaces Workspaces Get" } } } } } }, "post": { "tags": [ "Workspaces" ], "summary": "Create Workspace", "description": "Create a new workspace.\n\nCreator automatically receives ADMIN permissions on the workspace.", "operationId": "create_workspace", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/workspaces/{workspace_id}": { "get": { "tags": [ "Workspaces" ], "summary": "Get Workspace", "description": "Get a workspace by ID", "operationId": "get_workspace", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Workspaces" ], "summary": "Update Workspace", "description": "Update a workspace", "operationId": "update_workspace", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Workspaces" ], "summary": "Delete Workspace", "description": "Delete a workspace (requires ADMIN permission)", "operationId": "delete_workspace", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/workspaces/{workspace_id}/projects": { "get": { "tags": [ "Workspaces" ], "summary": "List Projects In Workspace", "description": "List all projects in a workspace that the user can access.\n\n- Workspace owners: see ALL projects\n- Workspace members: see projects where they have access (excludes no_access)\n- Member_limited users: see only projects with explicit permission (excludes no_access)\n\nOnly active projects are returned unless the status filter says otherwise.", "operationId": "list_projects_in_workspace", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ProjectStatusFilter", "description": "Filter projects by active status (active, inactive, or all). Defaults to active.", "default": "active" }, "description": "Filter projects by active status (active, inactive, or all). Defaults to active." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectResponse" }, "title": "Response List Projects In Workspace Workspaces Workspace Id Projects Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Workspaces" ], "summary": "Create Project In Workspace", "description": "Create a new project in a workspace", "operationId": "create_project_in_workspace", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/workspaces/{workspace_id}/users": { "get": { "tags": [ "Workspaces" ], "summary": "List Workspace Users", "description": "List all users in a workspace.\n\nThis includes people who were added but haven't signed up yet.\n\nLimited Members can't view the members list.\nOnly workspace owners and members can access this endpoint.", "operationId": "list_workspace_users", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceUserResponse" }, "title": "Response List Workspace Users Workspaces Workspace Id Users Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Workspaces" ], "summary": "Add User To Workspace", "description": "Add a user to a workspace with the specified role.\n\nIf the person has no Aspect account yet, they're invited by email.\n\nOnly workspace owners (ADMIN) can add users to a workspace.\nRole must be a valid workspace role: owner, member, or member_limited.", "operationId": "add_user_to_workspace", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAddUserRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUserResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/workspaces/{workspace_id}/users/{user_id}": { "delete": { "tags": [ "Workspaces" ], "summary": "Remove User From Workspace", "description": "Remove a user from a workspace.\n\nThis works for both full users and stub users. Removing a user from the workspace\nalso removes all their project-level permissions within this workspace.", "operationId": "remove_user_from_workspace", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "User Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Workspaces" ], "summary": "Update Workspace User Role", "description": "Update a user's role in a workspace.\n\nThis works for both full users and stub users.\n\nBusiness Rules:\n- Only workspace owners (ADMIN) can change user roles\n- Users cannot change their own role\n- Workspace must always have at least one owner\n- When promoting to owner: deletes all explicit project permissions (no longer needed)\n- When demoting from owner: no automatic project permissions created\n\nRole Conversion Logic:\n- Limited Member to Member: the project roles they were given stay as overrides\n- Member to Limited Member: their project roles stay and become their only access", "operationId": "update_workspace_user_role", "parameters": [ { "name": "workspace_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Workspace Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "User Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUpdateRoleRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUserResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/projects/{project_id}": { "get": { "tags": [ "Projects" ], "summary": "Get Project", "description": "Get a project by ID", "operationId": "get_project", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Projects" ], "summary": "Update Project", "description": "Update a project", "operationId": "update_project", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUpdateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Projects" ], "summary": "Delete Project", "description": "Delete a project.\n\nRequires workspace owner (ADMIN) permission. Workspace members cannot delete\nprojects, even ones they created. Project full_access role does not grant\ndelete permission.\n\nWhen a project is deleted, any member_limited users who only had access to\nthis project are automatically removed from the workspace.", "operationId": "delete_project", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/projects/{project_id}/shares": { "get": { "tags": [ "Projects" ], "summary": "List Project Shares", "description": "List all shares for resources within a project (requires FULL_ACCESS on project)", "operationId": "list_project_shares", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectShareListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/projects/{project_id}/users": { "get": { "tags": [ "Projects" ], "summary": "List Project Users", "description": "List all users with access to a project.\n\nReturns all users who can access this project, including:\n- Workspace owners (always have full access)\n- Workspace members (inherit project's default_role or have explicit permission)\n- Member_limited users with explicit project permission (including stub users)\n\nRequires VIEW permission on the project.\n\nDemo visitors cannot see who has access to a project.", "operationId": "list_project_users", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectUserResponse" }, "title": "Response List Project Users Projects Project Id Users Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Projects" ], "summary": "Add User To Project", "description": "Add a user to a project with the specified role.\n\nIf the person has no Aspect account yet, they're invited by email.\n\nRequirements:\n- Requires FULL_ACCESS on the project\n- Cannot set project permissions for workspace owners (they always have full access)\n- If the user doesn't have workspace access, auto-creates member_limited workspace permission,\n which takes a seat; only a workspace admin's add can buy that seat (`purchase_seat`)\n\nRole must be a valid project role: full_access, editor, commenter, downloader, viewer", "operationId": "add_user_to_project", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAddUserRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUserResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/projects/{project_id}/users/{user_id}": { "patch": { "tags": [ "Projects" ], "summary": "Update Project User Role", "description": "Update a user's role on a project.\n\nWorks for both full users and stub users.\n\nRequirements:\n- Requires FULL_ACCESS on the project\n- Cannot update project role for workspace owners\n- Role must be a valid project role: full_access, editor, commenter, downloader, viewer, no_access\n\nNote: For MEMBER_LIMITED users, setting NO_ACCESS removes their explicit permission\n(equivalent to DELETE) since they have no access without explicit permission.", "operationId": "update_project_user_role", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "User Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUpdateRoleRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUserResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Projects" ], "summary": "Remove User From Project", "description": "Remove a user's explicit project permission.\n\nWorks for both full users and stub users.\n\nRequirements:\n- Requires FULL_ACCESS on the project\n- Cannot remove project permission for workspace owners\n\nNote: If this is the user's last project access and they are a member_limited user,\nthey will be automatically removed from the workspace as well.", "operationId": "remove_user_from_project", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Project Id" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "User Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/directories/{directory_id}": { "get": { "tags": [ "Directories" ], "summary": "Get Directory", "description": "Get a directory by ID", "operationId": "get_directory", "parameters": [ { "name": "directory_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Directory Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Directories" ], "summary": "Update Directory", "description": "Rename a directory.", "operationId": "update_directory", "parameters": [ { "name": "directory_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Directory Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryUpdateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/directories/{directory_id}/details": { "get": { "tags": [ "Directories" ], "summary": "Get Directory Details", "description": "Get directory details including stats and creator info", "operationId": "get_directory_details", "parameters": [ { "name": "directory_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Directory Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryDetailsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/directories/delete": { "post": { "tags": [ "Directories" ], "summary": "Delete Directories", "description": "Permanently delete directories and everything in them. This can't be undone. To make it recoverable, move them to the trash instead.", "operationId": "delete_directories", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryDeleteRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryDeleteResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/directories/{directory_id}/path": { "get": { "tags": [ "Directories" ], "summary": "Get Directory Path", "description": "Get full directory path from root to current directory", "operationId": "get_directory_path", "parameters": [ { "name": "directory_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Directory Id" } }, { "name": "collection_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Optional collection ID to filter path by collection membership", "title": "Collection Id" }, "description": "Optional collection ID to filter path by collection membership" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PathSegment" }, "title": "Response Get Directory Path Directories Directory Id Path Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/directories/list": { "post": { "tags": [ "Directories" ], "summary": "List Directories", "description": "List all subdirectories under a parent directory", "operationId": "list_directories", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDirectoriesRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/DirectoryResponse" }, "type": "array", "title": "Response List Directories Directories List Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/directories/{directory_id}/directories": { "post": { "tags": [ "Directories" ], "summary": "Create Subdirectory", "description": "Create a new subdirectory in a directory", "operationId": "create_subdirectory", "parameters": [ { "name": "directory_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Directory Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryCreateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/collections": { "post": { "tags": [ "Collections" ], "summary": "Create Collection", "description": "Create a new collection in a project", "operationId": "create_collection", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Collections" ], "summary": "List Collections In Project", "description": "List all collections in a project", "operationId": "list_collections_in_project", "parameters": [ { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Project ID", "title": "Project Id" }, "description": "Project ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionResponse" }, "title": "Response List Collections In Project Collections Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/collections/{collection_id}": { "get": { "tags": [ "Collections" ], "summary": "Get Collection", "description": "Get a collection by ID", "operationId": "get_collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Collection Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Collections" ], "summary": "Update Collection", "description": "Update a collection", "operationId": "update_collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Collection Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Collections" ], "summary": "Delete Collection", "description": "Delete a collection (requires FULL_ACCESS permission)", "operationId": "delete_collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Collection Id" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/collections/{collection_id}/items": { "post": { "tags": [ "Collections" ], "summary": "Add Items To Collection", "description": "Add directories and/or assets to a collection", "operationId": "add_items_to_collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Collection Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionAddItemsRequest" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Collections" ], "summary": "Remove Items From Collection", "description": "Remove items from a collection", "operationId": "remove_items_from_collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Collection Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionRemoveItemsRequest" } } } }, "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/collections/{collection_id}/assets": { "post": { "tags": [ "Collections" ], "summary": "List Collection Assets", "description": "List assets in a collection with optional filters and sorting.\n\nReturns assets in collection's curated order by default.\nCustom sort overrides collection order.", "operationId": "list_collection_assets", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Collection Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCollectionAssetsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AssetResponse" }, "title": "Response List Collection Assets Collections Collection Id Assets Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/collections/{collection_id}/directories": { "get": { "tags": [ "Collections" ], "summary": "Get Collection Directories", "description": "Get all directories in a collection", "operationId": "get_collection_directories", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Collection Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryResponse" }, "title": "Response Get Collection Directories Collections Collection Id Directories Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/assets/list": { "post": { "tags": [ "Assets" ], "summary": "List Assets", "description": "List assets with optional filters and sorting.\n\nThis endpoint supports advanced filtering on both asset columns and metadata attributes.\nFilters are combined with AND logic.", "operationId": "list_assets", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAssetsRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AssetResponse" }, "type": "array", "title": "Response List Assets Assets List Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/assets/{asset_id}/path": { "get": { "tags": [ "Assets" ], "summary": "Get Asset Path", "description": "Get full path from root to the asset (including the asset itself)", "operationId": "get_asset_path", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Asset ID", "description": "The ID of the asset" }, "description": "The ID of the asset" }, { "name": "collection_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Optional collection ID to filter path by collection membership", "title": "Collection Id" }, "description": "Optional collection ID to filter path by collection membership" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PathSegment" }, "title": "Response Get Asset Path Assets Asset Id Path Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/assets/{asset_id}": { "put": { "tags": [ "Assets" ], "summary": "Update Asset", "description": "Update an asset by ID (rename)", "operationId": "update_asset", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Asset ID", "description": "The ID of the asset to update" }, "description": "The ID of the asset to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Assets" ], "summary": "Get Asset", "description": "Get asset details by ID.", "operationId": "get_asset", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Asset ID", "description": "The ID of the asset to get" }, "description": "The ID of the asset to get" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/assets/{asset_id}/thumbnail": { "put": { "tags": [ "Assets" ], "summary": "Set Asset Thumbnail", "description": "Set a custom thumbnail for the asset from a confirmed attachment.", "operationId": "set_asset_thumbnail", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Asset ID", "description": "The ID of the asset" }, "description": "The ID of the asset" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetThumbnailSetRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Assets" ], "summary": "Reset Asset Thumbnail", "description": "Reset the asset thumbnail to the generated preview.", "operationId": "reset_asset_thumbnail", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Asset ID", "description": "The ID of the asset" }, "description": "The ID of the asset" } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/assets/delete": { "post": { "tags": [ "Assets" ], "summary": "Delete Assets", "description": "Permanently delete assets. This can't be undone. To make it recoverable, move them to the trash instead.", "operationId": "delete_assets", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetDeleteRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetDeleteResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/assets/{asset_id}/download": { "get": { "tags": [ "Assets" ], "summary": "Get asset download URL", "description": "Get a temporary URL for one of the asset's files.\n\nEvery URL supports range requests. For `original`, each response's `ETag` is the asset's `manifest_id`:\nto resume a download without mixing two versions of the file, send that `ETag` back in `If-Range`.", "operationId": "get_asset_download_data", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Asset ID", "description": "The ID of the asset to download" }, "description": "The ID of the asset to download" }, { "name": "variant", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DownloadVariant", "title": "Variant", "description": "File to download: `original` (the uploaded file), `stream_proxy` (the web-playable copy), or `preview` (the thumbnail image).", "default": "original" }, "description": "File to download: `original` (the uploaded file), `stream_proxy` (the web-playable copy), or `preview` (the thumbnail image)." }, { "name": "prefer_custom_thumbnail", "in": "query", "required": false, "schema": { "type": "boolean", "title": "Prefer Custom Thumbnail", "description": "For `preview`, return the custom thumbnail when one is set instead of the generated preview.", "default": false }, "description": "For `preview`, return the custom thumbnail when one is set instead of the generated preview." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetDownloadGetResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/assets/versions/add": { "post": { "tags": [ "Assets" ], "summary": "Add To Version Stack", "description": "Add assets to a version stack, or create a new stack.\n\nThe target_asset_id becomes version 1 (or stays in its existing stack).\nThe asset_ids are added on top, with the last becoming the new top version.\nAll asset_ids must not already be in a version stack.", "operationId": "add_to_version_stack", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddToVersionStackRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionStackResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/assets/versions/remove": { "post": { "tags": [ "Assets" ], "summary": "Remove From Version Stack", "description": "Remove an asset from its version stack.\n\nThe asset becomes standalone (version fields set to NULL). If only one\nasset remains in the stack, the stack is dissolved and that asset also\nbecomes standalone.\n\nReturns 409 with conflict details if the removed asset's name conflicts\nwith an existing item in its parent directory.", "operationId": "remove_from_version_stack", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveFromVersionStackRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveFromVersionStackResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/assets/versions/{version_stack_id}": { "get": { "tags": [ "Assets" ], "summary": "List Version Stack", "description": "List all assets in a version stack, ordered from highest version number to lowest.", "operationId": "list_version_stack", "parameters": [ { "name": "version_stack_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Version Stack ID", "description": "The version stack ID" }, "description": "The version stack ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionStackResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/assets/versions/reorder": { "post": { "tags": [ "Assets" ], "summary": "Reorder Version Stack", "description": "Reorder assets within a version stack.\n\nThe last element of ordered_asset_ids becomes the new top version.\nReturns 409 with conflict details if the new top's name conflicts with\nan existing item.", "operationId": "reorder_version_stack", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderVersionStackRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionStackResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/fs-items/move": { "post": { "tags": [ "Filesystem Items" ], "summary": "Move Items", "description": "Move assets and directories into a directory.", "operationId": "move_items", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsItemsMoveRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsItemsMoveResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/fs-items/copy": { "post": { "tags": [ "Filesystem Items" ], "summary": "Copy Items", "description": "Copy items into a directory as a background job; poll GET /fs-items/copy/{job_id}.", "operationId": "copy_items", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsItemsCopyRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsItemsCopyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/fs-items/copy/{job_id}": { "get": { "tags": [ "Filesystem Items" ], "summary": "Get Copy Job", "description": "Get the status of a copy job. Only the user who started the copy can see it.", "operationId": "get_copy_job", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyJobResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/fs-items/move-to-trash": { "post": { "tags": [ "Filesystem Items" ], "summary": "Move To Trash", "description": "Move items to the project trash.", "operationId": "move_to_trash", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsItemsMoveToTrashRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsItemsMoveResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/fs-items/restore": { "post": { "tags": [ "Filesystem Items" ], "summary": "Restore Items", "description": "Restore items from the project trash.", "operationId": "restore_items", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsItemsRestoreRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsItemsRestoreResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/fs-items/empty-trash": { "post": { "tags": [ "Filesystem Items" ], "summary": "Empty Trash", "description": "Permanently delete everything in the project trash.", "operationId": "empty_trash", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsItemsEmptyTrashRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsItemsEmptyTrashResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/search/run": { "post": { "tags": [ "Search" ], "summary": "Search a project", "description": "Search a project's assets by what's seen, said, or written in them, and filter by metadata.", "operationId": "search", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/search/asset/{asset_id}/run": { "post": { "tags": [ "Search" ], "summary": "Search Asset", "description": "Find the moments in one asset that match a search.", "operationId": "search_asset", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Asset ID", "description": "The ID of the asset to search within" }, "description": "The ID of the asset to search within" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetSearchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchAssetMetadata" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api-keys": { "get": { "tags": [ "API Keys" ], "summary": "List API keys", "description": "List all API keys for the authenticated user.\n\nReturns key metadata without the actual key values.", "operationId": "list_api_keys", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ApiKeyGetResponse" }, "type": "array", "title": "Response List Api Keys Api Keys Get" } } } } } }, "post": { "tags": [ "API Keys" ], "summary": "Create API key", "description": "Create a new API key for the authenticated user.\n\nReturns the API key only once - it cannot be retrieved again for security reasons.", "operationId": "create_api_key", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api-keys/{api_key_id}": { "get": { "tags": [ "API Keys" ], "summary": "Get API key", "description": "Get details of a specific API key by ID.\n\nReturns key metadata without the actual key value.", "operationId": "get_api_key", "parameters": [ { "name": "api_key_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "API Key ID", "description": "The ID of the API key to retrieve" }, "description": "The ID of the API key to retrieve" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyGetResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "API Keys" ], "summary": "Delete API key", "description": "Delete an API key permanently.\n\nOnly the creator of the API key can delete it.", "operationId": "delete_api_key", "parameters": [ { "name": "api_key_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "API Key ID", "description": "The ID of the API key to delete" }, "description": "The ID of the API key to delete" } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/comments": { "post": { "tags": [ "Comments" ], "summary": "Create Comment", "description": "Create a comment or a reply on an asset.", "operationId": "create_comment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Comments" ], "summary": "Get Comments", "description": "Get all comments for a resource as a nested tree structure", "operationId": "get_comments", "parameters": [ { "name": "resource_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Resource ID", "description": "The ID of the asset to get comments for" }, "description": "The ID of the asset to get comments for" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CommentResponse" }, "title": "Response Get Comments Comments Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/comments/{comment_id}": { "get": { "tags": [ "Comments" ], "summary": "Get Comment", "description": "Get a single comment by ID", "operationId": "get_comment", "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Comment ID", "description": "The ID of the comment to get" }, "description": "The ID of the comment to get" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Comments" ], "summary": "Update Comment", "description": "Update comment text (only comment author can update)", "operationId": "update_comment", "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Comment ID", "description": "The ID of the comment to update" }, "description": "The ID of the comment to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Comments" ], "summary": "Delete Comment", "description": "Delete a comment (only comment author can delete)", "operationId": "delete_comment", "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Comment ID", "description": "The ID of the comment to delete" }, "description": "The ID of the comment to delete" } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/comments/{comment_id}/resolve": { "put": { "tags": [ "Comments" ], "summary": "Resolve Comment", "description": "Toggle comment resolved status (requires EDIT access to asset)", "operationId": "resolve_comment", "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Comment ID", "description": "The ID of the comment to resolve/unresolve" }, "description": "The ID of the comment to resolve/unresolve" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResolveRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/comments/{comment_id}/reactions": { "post": { "tags": [ "Comments" ], "summary": "Add Reaction", "description": "Add a reaction to a comment", "operationId": "add_reaction", "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Comment ID", "description": "The ID of the comment to add reaction to" }, "description": "The ID of the comment to add reaction to" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReactionAddRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/comments/{comment_id}/reactions/{reaction}": { "delete": { "tags": [ "Comments" ], "summary": "Remove Reaction", "description": "Remove a reaction from a comment", "operationId": "remove_reaction", "parameters": [ { "name": "comment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Comment ID", "description": "The ID of the comment to remove reaction from" }, "description": "The ID of the comment to remove reaction from" }, { "name": "reaction", "in": "path", "required": true, "schema": { "type": "string", "title": "Reaction", "description": "The reaction emoji/type to remove" }, "description": "The reaction emoji/type to remove" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/attachments/upload": { "post": { "tags": [ "Attachments" ], "summary": "Initiate Upload", "description": "Initiate an attachment upload.\n\nReturns a temporary upload URL.\nThe upload must be confirmed after the file is uploaded.", "operationId": "initiate_upload", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentUploadInitRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentUploadInitResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/attachments/{attachment_id}/confirm": { "post": { "tags": [ "Attachments" ], "summary": "Confirm Upload", "description": "Confirm that an attachment has been uploaded.\n\nMust be called after the file is uploaded to the upload URL.\nReturns the attachment with a download URL.", "operationId": "confirm_upload", "parameters": [ { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Attachment ID", "description": "The ID of the attachment to confirm" }, "description": "The ID of the attachment to confirm" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/attachments/{attachment_id}": { "get": { "tags": [ "Attachments" ], "summary": "Get Attachment", "description": "Get an attachment by ID.\n\nReturns the attachment with a download URL (if uploaded).\n\nAuthorization is based on the attachment's context:\n- No context: Only the uploader can access\n- Comment attachment: User must have VIEW access to the asset\n- Icon attachments: User must have VIEW access to the workspace/project/collection\n- Person and object reference photos: User must have VIEW access to the column's project", "operationId": "get_attachment", "parameters": [ { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Attachment ID", "description": "The ID of the attachment to get" }, "description": "The ID of the attachment to get" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/shares": { "post": { "tags": [ "Shares" ], "summary": "Create Share", "description": "Create a new share for a resource (requires FULL_ACCESS)", "operationId": "create_share", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Shares" ], "summary": "List Shares", "description": "List all shares for a resource (requires FULL_ACCESS)", "operationId": "list_shares", "parameters": [ { "name": "resource_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Resource id being shared (collection, directory, asset)", "title": "Resource Id" }, "description": "Resource id being shared (collection, directory, asset)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/shares/{share_id}/password": { "get": { "tags": [ "Shares" ], "summary": "Get Share Password", "description": "Reveal the current share password to an authorized user.", "operationId": "get_share_password", "parameters": [ { "name": "share_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Share id", "title": "Share Id" }, "description": "Share id" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharePasswordResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/shares/oembed": { "get": { "tags": [ "Shares" ], "summary": "Resolve share oEmbed", "description": "Resolve a public share URL into oEmbed (https://oembed.com) embed metadata.", "operationId": "get_share_oembed", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "description": "Share URL to resolve into embed markup", "title": "Url" }, "description": "Share URL to resolve into embed markup" }, { "name": "format", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Response format; only json is supported", "title": "Format" }, "description": "Response format; only json is supported" }, { "name": "maxwidth", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Maximum width of the embed in pixels", "title": "Maxwidth" }, "description": "Maximum width of the embed in pixels" }, { "name": "maxheight", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Maximum height of the embed in pixels", "title": "Maxheight" }, "description": "Maximum height of the embed in pixels" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicShareOEmbedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [] } }, "/shares/{share_id}": { "get": { "tags": [ "Shares" ], "summary": "Get Share", "description": "Get share details by ID (public, no auth required)", "operationId": "get_share", "parameters": [ { "name": "share_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Share id", "title": "Share Id" }, "description": "Share id" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Shares" ], "summary": "Update Share", "description": "Update a share (requires FULL_ACCESS on the resource)", "operationId": "update_share", "parameters": [ { "name": "share_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Share id", "title": "Share Id" }, "description": "Share id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Shares" ], "summary": "Delete Share", "description": "Delete a share (requires FULL_ACCESS on the resource)", "operationId": "delete_share", "parameters": [ { "name": "share_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Share id", "title": "Share Id" }, "description": "Share id" } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/share-templates": { "get": { "tags": [ "Share Templates" ], "summary": "List Share Templates", "description": "List all share templates in a workspace.", "operationId": "list_share_templates", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Workspace ID to list share templates for", "title": "Workspace Id" }, "description": "Workspace ID to list share templates for" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ShareTemplateResponse" }, "title": "Response List Share Templates Share Templates Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Share Templates" ], "summary": "Create Share Template", "description": "Create a new share template in a workspace.", "operationId": "create_share_template", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareTemplateCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareTemplateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/share-templates/{share_template_id}": { "put": { "tags": [ "Share Templates" ], "summary": "Update Share Template", "description": "Update a share template.", "operationId": "update_share_template", "parameters": [ { "name": "share_template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Share template id", "title": "Share Template Id" }, "description": "Share template id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareTemplateUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareTemplateResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Share Templates" ], "summary": "Delete Share Template", "description": "Delete a share template.", "operationId": "delete_share_template", "parameters": [ { "name": "share_template_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Share template id", "title": "Share Template Id" }, "description": "Share template id" } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/watermarks": { "post": { "tags": [ "Watermarks" ], "summary": "Create Watermark", "description": "Create a new watermark in a workspace.", "operationId": "create_watermark", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatermarkCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatermarkResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "Watermarks" ], "summary": "List Watermarks", "description": "List all watermarks in a workspace.", "operationId": "list_watermarks", "parameters": [ { "name": "workspace_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Workspace ID to list watermarks for", "title": "Workspace Id" }, "description": "Workspace ID to list watermarks for" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WatermarkResponse" }, "title": "Response List Watermarks Watermarks Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/watermarks/{watermark_id}": { "get": { "tags": [ "Watermarks" ], "summary": "Get Watermark", "description": "Get a watermark by ID.", "operationId": "get_watermark", "parameters": [ { "name": "watermark_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Watermark Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatermarkResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "Watermarks" ], "summary": "Update Watermark", "description": "Update a watermark.", "operationId": "update_watermark", "parameters": [ { "name": "watermark_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Watermark Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatermarkUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatermarkResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Watermarks" ], "summary": "Delete Watermark", "description": "Delete a watermark.\n\nIf the watermark is in use by shares, returns 409 with the share count.\nTo proceed, either:\n- Set force=true to delete and remove watermarking from affected shares\n- Set replace_with={other_watermark_id} to reassign affected shares first", "operationId": "delete_watermark", "parameters": [ { "name": "watermark_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Watermark Id" } }, { "name": "force", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Force deletion even if the watermark is in use by shares", "default": false, "title": "Force" }, "description": "Force deletion even if the watermark is in use by shares" }, { "name": "replace_with", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Reassign affected shares to this watermark before deleting", "title": "Replace With" }, "description": "Reassign affected shares to this watermark before deleting" } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/transcription": { "get": { "tags": [ "Transcription" ], "summary": "Get transcription", "description": "Get transcription paragraphs and words for an asset", "operationId": "get_transcription_by_asset_id", "parameters": [ { "name": "asset_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Asset ID", "description": "The ID of the asset to get transcription for" }, "description": "The ID of the asset to get transcription for" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/transcription/export": { "get": { "tags": [ "Transcription" ], "summary": "Export Transcription", "description": "Export an asset's transcript as a downloadable VTT/SRT/TXT/MD file", "operationId": "export_transcription", "parameters": [ { "name": "asset_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Asset ID", "description": "The ID of the asset to export the transcript for" }, "description": "The ID of the asset to export the transcript for" }, { "name": "export_format", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/ExportFormat", "title": "Export format", "description": "Transcript export format" }, "description": "Transcript export format" } ], "responses": { "200": { "description": "The transcript file", "content": { "text/vtt": { "schema": { "type": "string" } }, "application/x-subrip": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } }, "text/markdown": { "schema": { "type": "string" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/metadata/attributes": { "get": { "tags": [ "Metadata" ], "summary": "List Attributes", "description": "List all metadata attributes.\n\nIf project_id is provided, includes project-specific attributes (user attributes and project system attributes).\nAlways includes system global attributes.\n\nFor share users, hidden attributes (configured in share settings) are filtered out from the response.", "operationId": "list_attributes", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Project ID to include project-specific attributes", "title": "Project Id" }, "description": "Project ID to include project-specific attributes" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataAttributeResponse" }, "title": "Response List Attributes Metadata Attributes Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Metadata" ], "summary": "Create Attribute", "description": "Create a new project-specific user attribute (manually populated).", "operationId": "create_attribute", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataAttributeCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataAttributeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/metadata/attributes/stats": { "get": { "tags": [ "Metadata" ], "summary": "Get Generation Stats", "description": "AI generation progress for each attribute that has generation turned on. A run is done when `pending` is 0.", "operationId": "get_generation_stats", "parameters": [ { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Project ID", "title": "Project Id" }, "description": "Project ID" }, { "name": "attribute_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, { "type": "null" } ], "description": "Only return stats for these attributes", "title": "Attribute Ids" }, "description": "Only return stats for these attributes" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataGenerationStatsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/metadata/attributes/{attribute_id}": { "get": { "tags": [ "Metadata" ], "summary": "Get Attribute", "description": "Get a single metadata attribute by ID.\n\nSystem global attributes are readable by any authenticated user.\nFor share users, hidden attributes (configured in share settings) return 404.", "operationId": "get_attribute", "parameters": [ { "name": "attribute_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Attribute ID", "title": "Attribute Id" }, "description": "Attribute ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataAttributeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Metadata" ], "summary": "Update Attribute", "description": "Update a project-specific metadata attribute.\n\nCannot update global attributes (source IN (SYSTEM, ASSET) & project_id=null).", "operationId": "update_attribute", "parameters": [ { "name": "attribute_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Attribute ID", "title": "Attribute Id" }, "description": "Attribute ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataAttributeUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataAttributeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Metadata" ], "summary": "Delete Attribute", "description": "Delete a project-specific metadata attribute.\n\nCannot delete global attributes (source IN (SYSTEM, ASSET), project_id=null).", "operationId": "delete_attribute", "parameters": [ { "name": "attribute_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Attribute ID", "title": "Attribute Id" }, "description": "Attribute ID" } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/metadata/attributes/{attribute_id}/run": { "post": { "tags": [ "Metadata" ], "summary": "Run Generation", "description": "Start AI generation for this attribute.\n\n- `mode`: `fill` generates missing and failed values. `overwrite` regenerates all values.\n- `replace_manual`: if `true`, an `overwrite` run also regenerates manually entered values. Ignored by `fill`. Default `false`.\n- `target`: `watch` (the watch directories), `directories`, or `assets`.\n\nTo track progress, call `GET /metadata/attributes/stats`.", "operationId": "run_generation", "parameters": [ { "name": "attribute_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Attribute ID", "title": "Attribute Id" }, "description": "Attribute ID" }, { "name": "dry_run", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Count the assets the run would cover without starting it. Not supported when `target.kind` is `assets`.", "default": false, "title": "Dry Run" }, "description": "Count the assets the run would cover without starting it. Not supported when `target.kind` is `assets`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CellRunRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CellRunResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/metadata/attributes/{attribute_id}/stop": { "post": { "tags": [ "Metadata" ], "summary": "Stop Generation", "description": "Cancel pending AI generation for this attribute. Values already generated are kept.", "operationId": "stop_generation", "parameters": [ { "name": "attribute_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Attribute ID", "title": "Attribute Id" }, "description": "Attribute ID" }, { "name": "dry_run", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Count the assets whose pending generation would be cancelled, without cancelling it.", "default": false, "title": "Dry Run" }, "description": "Count the assets whose pending generation would be cancelled, without cancelling it." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CellStopResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/metadata/assets/{asset_id}": { "get": { "tags": [ "Metadata" ], "summary": "Get Asset Metadata Values", "description": "Get all metadata values for an asset.\n\nFor share users, hidden attributes (configured in share settings) are filtered out.", "operationId": "get_asset_metadata_values", "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Asset ID", "title": "Asset Id" }, "description": "Asset ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetMetadataResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/metadata/attributes/{attribute_id}/assets/{asset_id}": { "put": { "tags": [ "Metadata" ], "summary": "Set Asset Metadata Value", "description": "Set a metadata value for an asset.\n\nThe attribute must belong to the asset's project (otherwise `404`) and be editable (`is_editable`, otherwise `400`).", "operationId": "set_asset_metadata_value", "parameters": [ { "name": "attribute_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Attribute ID", "title": "Attribute Id" }, "description": "Attribute ID" }, { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Asset ID", "title": "Asset Id" }, "description": "Asset ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataValueSetRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataValueResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "AddToVersionStackRequest": { "properties": { "asset_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Asset Ids", "description": "IDs of assets to add to the stack. These must not already be in a stack." }, "target_asset_id": { "type": "string", "format": "uuid", "title": "Target Asset Id", "description": "ID of the target asset. If not in a stack, a new stack is created with this asset as version 1." } }, "type": "object", "required": [ "asset_ids", "target_asset_id" ], "title": "AddToVersionStackRequest", "description": "API request to add assets to a version stack (or create a new stack)" }, "AnchorPosition": { "properties": { "x": { "type": "number", "maximum": 100.0, "minimum": 0.0, "title": "X", "description": "Distance from the left edge, from 0 to 100" }, "y": { "type": "number", "maximum": 100.0, "minimum": 0.0, "title": "Y", "description": "Distance from the top edge, from 0 to 100" } }, "type": "object", "required": [ "x", "y" ], "title": "AnchorPosition", "description": "A point on the frame, image, or page, in percent of its size." }, "AnnotationPoint": { "properties": { "x": { "type": "number", "title": "X", "description": "Distance from the left edge, from 0 to 1" }, "y": { "type": "number", "title": "Y", "description": "Distance from the top edge, from 0 to 1" } }, "type": "object", "required": [ "x", "y" ], "title": "AnnotationPoint", "description": "A point on the frame, image, or page, as a fraction of its size." }, "ApiKeyCreateRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "Human-readable name for the API key" } }, "type": "object", "required": [ "name" ], "title": "ApiKeyCreateRequest", "description": "API request schema for creating an API key" }, "ApiKeyCreateResponse": { "properties": { "api_key": { "type": "string", "title": "Api Key", "description": "The key value. It's returned only once, so store it now." }, "key_info": { "$ref": "#/components/schemas/ApiKeyGetResponse", "description": "Key metadata" } }, "type": "object", "required": [ "api_key", "key_info" ], "title": "ApiKeyCreateResponse", "description": "API response schema returned after creating a new API key (includes the raw key once)." }, "ApiKeyGetResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "key_prefix": { "type": "string", "title": "Key Prefix" }, "created": { "type": "string", "format": "date-time", "title": "Created" }, "last_used": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Used" } }, "type": "object", "required": [ "id", "name", "key_prefix", "created", "last_used" ], "title": "ApiKeyGetResponse", "description": "API response schema for getting API key metadata (no sensitive key value)." }, "ArrowPath": { "properties": { "tool": { "type": "string", "const": "arrow", "title": "Tool" }, "color": { "type": "string", "title": "Color", "description": "Hex color, such as `#22C55E`" }, "stroke_width": { "type": "number", "title": "Stroke Width", "description": "Line width in screen pixels" }, "start": { "$ref": "#/components/schemas/AnnotationPoint" }, "end": { "$ref": "#/components/schemas/AnnotationPoint" } }, "type": "object", "required": [ "tool", "color", "stroke_width", "start", "end" ], "title": "ArrowPath", "description": "An arrow pointing from `start` to `end`." }, "AssetDeleteRequest": { "properties": { "asset_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Asset Ids", "description": "List of asset IDs to delete" } }, "type": "object", "required": [ "asset_ids" ], "title": "AssetDeleteRequest", "description": "API request schema for bulk deleting assets" }, "AssetDeleteResponse": { "properties": { "deleted_count": { "type": "integer", "title": "Deleted Count", "description": "Number of assets successfully deleted" } }, "type": "object", "required": [ "deleted_count" ], "title": "AssetDeleteResponse", "description": "API response schema for bulk deleting assets" }, "AssetDownloadGetResponse": { "properties": { "url": { "type": "string", "title": "Url", "description": "Temporary URL for the upload or download" }, "url_expires_at": { "type": "string", "format": "date-time", "title": "Url Expires At", "description": "UTC datetime when the URL expires" } }, "type": "object", "required": [ "url", "url_expires_at" ], "title": "AssetDownloadGetResponse", "description": "API response schema for direct asset file download URLs." }, "AssetMedia": { "properties": { "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Width", "description": "Pixel width for visual assets. Null when unknown." }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Height", "description": "Pixel height for visual assets. Null when unknown." }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Duration", "description": "Duration in seconds for time-based assets. Null for assets without a duration." }, "frame_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Frame Rate", "description": "Frames per second for video assets. Null for non-video assets." }, "timecode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timecode", "description": "SMPTE start timecode, such as `01:00:00:00` (`01:00:00;00` for drop-frame). Null when the file has none." }, "page_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page Count", "description": "Number of pages for document assets. Null for non-document assets." } }, "type": "object", "title": "AssetMedia", "description": "Intrinsic media properties extracted from the asset's content." }, "AssetMetadataResponse": { "properties": { "asset_id": { "type": "string", "format": "uuid", "title": "Asset Id", "description": "ID of the asset" }, "values": { "items": { "$ref": "#/components/schemas/MetadataValue" }, "type": "array", "title": "Values", "description": "All metadata values for the asset" } }, "type": "object", "required": [ "asset_id", "values" ], "title": "AssetMetadataResponse", "description": "API response schema containing all metadata for an asset." }, "AssetResponse": { "properties": { "symlink": { "anyOf": [ { "$ref": "#/components/schemas/SymlinkInfo" }, { "type": "null" } ], "description": "Set only on symlinks: items, made by the desktop app or local drive, that point to another asset or directory. Pass a symlink's `id` in `symlink_ids` to move, trash, restore, or copy it; use `symlink.target_id` for everything else." }, "id": { "type": "string", "format": "uuid", "title": "Id" }, "type": { "$ref": "#/components/schemas/AssetType", "description": "Type of the asset (video, image, etc)" }, "name": { "type": "string", "title": "Name" }, "size_bytes": { "type": "integer", "title": "Size Bytes" }, "media": { "$ref": "#/components/schemas/AssetMedia", "description": "Intrinsic media properties (dimensions, duration, frame rate, timecode, page count)" }, "mime_type": { "type": "string", "title": "Mime Type" }, "is_uploaded": { "type": "boolean", "title": "Is Uploaded" }, "is_generated": { "type": "boolean", "title": "Is Generated", "description": "Whether this asset was produced by the AI generation pipeline", "default": false }, "workspace_id": { "type": "string", "format": "uuid", "title": "Workspace Id", "description": "ID of the workspace this asset belongs to" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "ID of the project this asset belongs to" }, "parent_id": { "type": "string", "format": "uuid", "title": "Parent Id", "description": "ID of the parent resource (directory or project)" }, "comment_count": { "type": "integer", "title": "Comment Count", "description": "Total number of visible comments on this asset, including replies" }, "created_by_user_id": { "type": "string", "format": "uuid", "title": "Created By User Id", "description": "ID of the user that created the asset" }, "version_stack_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Version Stack Id", "description": "Version stack ID. Null if the asset isn't in a stack." }, "version_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Version Number", "description": "Position in the version stack, starting at 1. Null if the asset isn't in a stack." }, "is_top_version": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Top Version", "description": "True for the top version of a stack. Null if the asset isn't in a stack." }, "manifest_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Manifest Id", "description": "ID of the asset's current file content. It changes whenever the content changes. Null when the asset has no content yet." }, "created": { "type": "string", "format": "date-time", "title": "Created" }, "updated": { "type": "string", "format": "date-time", "title": "Updated" }, "content_modified_at": { "type": "string", "format": "date-time", "title": "Content Modified At", "description": "When the asset's file content last changed. Renames and metadata edits don't change it." } }, "type": "object", "required": [ "id", "type", "name", "size_bytes", "mime_type", "is_uploaded", "workspace_id", "project_id", "parent_id", "comment_count", "created_by_user_id", "created", "updated", "content_modified_at" ], "title": "AssetResponse", "description": "An asset." }, "AssetSearchRequest": { "properties": { "project_id": { "type": "string", "format": "uuid", "title": "Project ID", "description": "ID of the project the asset belongs to" }, "spec": { "$ref": "#/components/schemas/UserSearchSpec", "title": "Spec", "description": "What to search for and how to filter. Needs at least one signal or filter." } }, "additionalProperties": false, "type": "object", "required": [ "project_id", "spec" ], "title": "AssetSearchRequest", "description": "API request schema for searching within a specific asset." }, "AssetThumbnailSetRequest": { "properties": { "attachment_id": { "type": "string", "format": "uuid", "title": "Attachment Id", "description": "Confirmed attachment to set as the custom thumbnail" } }, "type": "object", "required": [ "attachment_id" ], "title": "AssetThumbnailSetRequest", "description": "API request schema for setting an asset's custom thumbnail" }, "AssetType": { "type": "string", "enum": [ "video", "image", "audio", "document", "vector", "other" ], "title": "AssetType" }, "AssetUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Asset Name", "description": "The name of the asset. Must include the extension." } }, "type": "object", "title": "AssetUpdateRequest", "description": "API request schema for updating an asset" }, "AssetsRunTarget": { "properties": { "kind": { "type": "string", "const": "assets", "title": "Kind" }, "asset_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "minItems": 1, "title": "Asset IDs", "description": "Assets to run on" } }, "type": "object", "required": [ "kind", "asset_ids" ], "title": "AssetsRunTarget", "description": "Only the listed assets, wherever they are." }, "AttachmentResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Resource identifier" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "Temporary download URL" }, "url_expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Url Expires At", "description": "When the URL expires" }, "filename": { "type": "string", "title": "Filename", "description": "Original filename" }, "mime_type": { "type": "string", "title": "Mime Type", "description": "MIME type of the file" }, "size_bytes": { "type": "integer", "title": "Size Bytes", "description": "File size in bytes" }, "uploaded": { "type": "boolean", "title": "Uploaded", "description": "Whether the file has been uploaded" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "Created timestamp" } }, "type": "object", "required": [ "id", "filename", "mime_type", "size_bytes", "uploaded", "created" ], "title": "AttachmentResponse", "description": "An attachment with a temporary download URL; url and url_expires_at are null until the upload is confirmed." }, "AttachmentUploadInitRequest": { "properties": { "filename": { "type": "string", "maxLength": 255, "title": "Filename", "description": "Original filename" }, "mime_type": { "type": "string", "maxLength": 127, "title": "Mime Type", "description": "MIME type of the file" }, "size_bytes": { "type": "integer", "maximum": 100000000.0, "exclusiveMinimum": 0.0, "title": "Size Bytes", "description": "File size in bytes (max 100MB)" } }, "type": "object", "required": [ "filename", "mime_type", "size_bytes" ], "title": "AttachmentUploadInitRequest", "description": "API request schema for initiating an attachment upload" }, "AttachmentUploadInitResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Resource identifier" }, "url": { "type": "string", "title": "Url", "description": "Temporary URL for the upload or download" }, "url_expires_at": { "type": "string", "format": "date-time", "title": "Url Expires At", "description": "UTC datetime when the URL expires" } }, "type": "object", "required": [ "id", "url", "url_expires_at" ], "title": "AttachmentUploadInitResponse", "description": "Temporary upload URL for a new attachment. `PUT` the file bytes to `url`, then call confirm." }, "AutoRenameStyle": { "type": "string", "enum": [ "parenthesized", "numeric" ], "title": "AutoRenameStyle", "description": "Style for auto-renaming items when name conflicts occur during creation" }, "BoxPath": { "properties": { "tool": { "type": "string", "const": "box", "title": "Tool" }, "color": { "type": "string", "title": "Color", "description": "Hex color, such as `#22C55E`" }, "stroke_width": { "type": "number", "title": "Stroke Width", "description": "Line width in screen pixels" }, "start": { "$ref": "#/components/schemas/AnnotationPoint" }, "end": { "$ref": "#/components/schemas/AnnotationPoint" } }, "type": "object", "required": [ "tool", "color", "stroke_width", "start", "end" ], "title": "BoxPath", "description": "A rectangle with opposite corners at `start` and `end`." }, "CellColumnStats": { "properties": { "column_id": { "type": "string", "format": "uuid", "title": "Column Id", "description": "Attribute ID" }, "pending": { "type": "integer", "title": "Pending", "description": "Assets with generation scheduled or in progress" }, "coverage": { "anyOf": [ { "$ref": "#/components/schemas/CellCoverage" }, { "type": "null" } ], "description": "Counts over the attribute's watch; null when it watches nothing" } }, "type": "object", "required": [ "column_id", "pending" ], "title": "CellColumnStats", "description": "AI generation progress for one attribute. `pending` counts every\nscheduled generation, including runs outside the watch." }, "CellCoverage": { "properties": { "eligible": { "type": "integer", "title": "Eligible", "description": "Assets the watch covers" }, "run": { "type": "integer", "title": "Run", "description": "Watched assets with a value, empty values included" }, "failed": { "type": "integer", "title": "Failed", "description": "Watched assets with no value whose last generation failed" }, "not_run": { "type": "integer", "title": "Not Run", "description": "Watched assets with no value and no failed generation" } }, "type": "object", "required": [ "eligible", "run", "failed", "not_run" ], "title": "CellCoverage", "description": "Counts over the assets an attribute watches: `eligible` is `run` +\n`failed` + `not_run`. An asset that keeps its value after a failed\nregeneration counts as run." }, "CellMode": { "type": "string", "enum": [ "fill", "overwrite" ], "title": "CellMode", "description": "`fill` generates missing and failed values. `overwrite` regenerates all values." }, "CellRunRequest": { "properties": { "mode": { "$ref": "#/components/schemas/CellMode", "title": "Run Mode", "description": "`fill` runs only the assets not run yet (or whose last run failed); `overwrite` re-runs every asset, replacing the AI's answers; answers entered by hand are kept unless `replace_manual` is true" }, "replace_manual": { "type": "boolean", "title": "Replace Manual Answers", "description": "With `overwrite`, also replace answers entered by hand. Ignored by `fill`", "default": false }, "target": { "oneOf": [ { "$ref": "#/components/schemas/WatchRunTarget" }, { "$ref": "#/components/schemas/DirectoriesRunTarget" }, { "$ref": "#/components/schemas/AssetsRunTarget" } ], "title": "Run Target", "description": "Which assets the run covers: `watch` = every asset in the watch directories, rejected when there are none; `directories` = assets in the given directories (`recursive: true` includes their subdirectories); `assets` = only the listed assets, wherever they are", "discriminator": { "propertyName": "kind", "mapping": { "assets": "#/components/schemas/AssetsRunTarget", "directories": "#/components/schemas/DirectoriesRunTarget", "watch": "#/components/schemas/WatchRunTarget" } } } }, "type": "object", "required": [ "mode", "target" ], "title": "CellRunRequest", "description": "API request schema for a run: what it does and which assets it covers." }, "CellRunResponse": { "properties": { "count": { "type": "integer", "title": "Count", "description": "Assets the run covers. Hand-entered values are included only with `replace_manual`." }, "manually_entered": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Manually Entered", "description": "Assets with a hand-entered value. Set only by `overwrite` dry runs." } }, "type": "object", "required": [ "count" ], "title": "CellRunResponse", "description": "API response schema for an explicit run's counts." }, "CellSource": { "type": "string", "enum": [ "user", "ai" ], "title": "CellSource", "description": "Who wrote the value: a user or AI." }, "CellStopResponse": { "properties": { "count": { "type": "integer", "title": "Count", "description": "Number of assets whose pending generation was cancelled" } }, "type": "object", "required": [ "count" ], "title": "CellStopResponse", "description": "API response schema for Stop running's entry count." }, "CollectionAddItemsRequest": { "properties": { "resource_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Resource Ids", "description": "IDs of assets or directories." } }, "type": "object", "required": [ "resource_ids" ], "title": "CollectionAddItemsRequest", "description": "API request schema for adding items to a collection" }, "CollectionCreateRequest": { "properties": { "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "Project ID" }, "name": { "type": "string", "title": "Name", "description": "Name of the collection" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description of the collection" } }, "type": "object", "required": [ "project_id", "name" ], "title": "CollectionCreateRequest", "description": "API request schema for creating a collection" }, "CollectionRemoveItemsRequest": { "properties": { "resource_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Resource Ids", "description": "IDs of assets or directories." } }, "type": "object", "required": [ "resource_ids" ], "title": "CollectionRemoveItemsRequest", "description": "API request schema for removing items from a collection" }, "CollectionResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Collection ID" }, "name": { "type": "string", "title": "Name", "description": "Collection name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Collection description" }, "created_by_user_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Created By User Id", "description": "User who created this collection" }, "num_assets": { "type": "integer", "title": "Num Assets", "description": "Number of assets in the collection", "default": 0 }, "num_directories": { "type": "integer", "title": "Num Directories", "description": "Number of directories in the collection", "default": 0 }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "Project ID" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "Creation timestamp" }, "updated": { "type": "string", "format": "date-time", "title": "Updated", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "name", "project_id", "created", "updated" ], "title": "CollectionResponse", "description": "API response schema for creating a collection" }, "CollectionUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "New name for the collection" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "New description for the collection" } }, "type": "object", "title": "CollectionUpdateRequest", "description": "API request schema for updating a collection" }, "CommentCreateRequest": { "properties": { "resource_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Resource Id", "description": "Asset to comment on" }, "text": { "type": "string", "title": "Text", "description": "Comment text content" }, "parent_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Id", "description": "Parent comment ID for replies" }, "timestamp": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Timestamp", "description": "Video timestamp in seconds" }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Duration", "description": "Duration in seconds for range comments" }, "anchor_position": { "anyOf": [ { "$ref": "#/components/schemas/AnchorPosition" }, { "type": "null" } ], "description": "Where the comment is pinned on the frame, image, or page" }, "annotation": { "anyOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/PenPath" }, { "$ref": "#/components/schemas/LinePath" }, { "$ref": "#/components/schemas/ArrowPath" }, { "$ref": "#/components/schemas/BoxPath" } ], "discriminator": { "propertyName": "tool", "mapping": { "arrow": "#/components/schemas/ArrowPath", "box": "#/components/schemas/BoxPath", "line": "#/components/schemas/LinePath", "pen": "#/components/schemas/PenPath" } } }, "type": "array" }, { "type": "null" } ], "title": "Annotation", "description": "Shapes drawn on the frame, image, or page" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page", "description": "Page number (1-indexed) for document comments" }, "text_highlight": { "anyOf": [ { "$ref": "#/components/schemas/TextHighlight" }, { "type": "null" } ], "description": "The document text the comment highlights" }, "mentions": { "items": { "$ref": "#/components/schemas/MentionCreateData" }, "type": "array", "title": "Mentions", "description": "User mentions in the comment" }, "attachment_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Attachment Ids", "description": "Attachment IDs to link to the comment" }, "private": { "type": "boolean", "title": "Private", "description": "Hidden from share-link guests.", "default": false } }, "type": "object", "required": [ "text" ], "title": "CommentCreateRequest", "description": "API request schema for creating a comment" }, "CommentResolveRequest": { "properties": { "is_resolved": { "type": "boolean", "title": "Is Resolved", "description": "New resolved status" } }, "type": "object", "required": [ "is_resolved" ], "title": "CommentResolveRequest", "description": "API request schema for resolving/unresolving a comment" }, "CommentResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Comment ID" }, "resource_id": { "type": "string", "format": "uuid", "title": "Resource Id", "description": "Asset the comment is on" }, "parent_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Id", "description": "Parent comment ID. Null for top-level comments." }, "text": { "type": "string", "title": "Text", "description": "Comment text" }, "timestamp": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Timestamp", "description": "Video timestamp in seconds" }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Duration", "description": "Duration in seconds for range comments" }, "anchor_position": { "anyOf": [ { "$ref": "#/components/schemas/AnchorPosition" }, { "type": "null" } ], "description": "Where the comment is pinned on the frame, image, or page" }, "annotation": { "anyOf": [ { "items": { "oneOf": [ { "$ref": "#/components/schemas/PenPath" }, { "$ref": "#/components/schemas/LinePath" }, { "$ref": "#/components/schemas/ArrowPath" }, { "$ref": "#/components/schemas/BoxPath" } ], "discriminator": { "propertyName": "tool", "mapping": { "arrow": "#/components/schemas/ArrowPath", "box": "#/components/schemas/BoxPath", "line": "#/components/schemas/LinePath", "pen": "#/components/schemas/PenPath" } } }, "type": "array" }, { "type": "null" } ], "title": "Annotation", "description": "Shapes drawn on the frame, image, or page" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page", "description": "Page number (1-indexed) for document comments" }, "text_highlight": { "anyOf": [ { "$ref": "#/components/schemas/TextHighlight" }, { "type": "null" } ], "description": "The document text the comment highlights" }, "is_resolved": { "type": "boolean", "title": "Is Resolved", "description": "Whether the thread is resolved" }, "private": { "type": "boolean", "title": "Private", "description": "Hidden from share-link guests." }, "number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Number", "description": "The comment's number on the asset, as in #3. Null for replies." }, "user": { "anyOf": [ { "$ref": "#/components/schemas/UserInfo" }, { "type": "null" } ], "description": "Comment author. Null if the author's account was deleted." }, "replies": { "items": { "$ref": "#/components/schemas/CommentResponse" }, "type": "array", "title": "Replies", "description": "Replies to this comment" }, "reactions": { "items": { "$ref": "#/components/schemas/ReactionGroup" }, "type": "array", "title": "Reactions", "description": "Reactions grouped by emoji" }, "mentions": { "items": { "$ref": "#/components/schemas/MentionInfo" }, "type": "array", "title": "Mentions", "description": "Users mentioned in the text" }, "attachments": { "items": { "$ref": "#/components/schemas/SignedAttachment" }, "type": "array", "title": "Attachments", "description": "Attached files" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "Creation timestamp" }, "updated": { "type": "string", "format": "date-time", "title": "Updated", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "resource_id", "parent_id", "text", "timestamp", "duration", "page", "is_resolved", "private", "number", "user", "replies", "reactions", "mentions", "attachments", "created", "updated" ], "title": "CommentResponse", "description": "API response schema for a single comment with nested replies, reactions, mentions, and attachments" }, "CommentUpdateRequest": { "properties": { "text": { "type": "string", "title": "Text", "description": "Updated comment text" }, "mentions": { "items": { "$ref": "#/components/schemas/MentionCreateData" }, "type": "array", "title": "Mentions", "description": "User mentions in the comment" }, "attachment_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Attachment Ids", "description": "Attachment IDs to link to the comment (replaces existing)" }, "timestamp": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Timestamp", "description": "Video timestamp in seconds. Send a negative number to remove it." }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Duration", "description": "Duration in seconds for range comments. Send a negative number to remove it." }, "private": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Private", "description": "Hidden from share-link guests. Only for root comments." } }, "type": "object", "required": [ "text" ], "title": "CommentUpdateRequest", "description": "API request schema for updating a comment" }, "CompactPoints": { "properties": { "x": { "items": { "type": "number" }, "type": "array", "title": "X", "description": "Distances from the left edge" }, "y": { "items": { "type": "number" }, "type": "array", "title": "Y", "description": "Distances from the top edge" } }, "type": "object", "required": [ "x", "y" ], "title": "CompactPoints", "description": "Pen points as two lists: point n is (`x[n]`, `y[n]`), each from 0 to 1." }, "ConfidenceRating": { "type": "string", "enum": [ "unknown", "low", "medium", "high" ], "title": "ConfidenceRating", "description": "How strong a search match is." }, "CopyJobFailedItem": { "properties": { "source_id": { "type": "string", "format": "uuid", "title": "Source Id", "description": "ID of the item that was being copied" }, "name": { "type": "string", "title": "Name", "description": "Name of the item" }, "error": { "type": "string", "title": "Error", "description": "Why the item could not be copied" } }, "type": "object", "required": [ "source_id", "name", "error" ], "title": "CopyJobFailedItem", "description": "An item that could not be copied." }, "CopyJobProgress": { "properties": { "percent": { "type": "number", "title": "Percent", "description": "Share of items copied or failed, from 0 to 1" }, "items_done": { "type": "integer", "title": "Items Done", "description": "Number of items copied" }, "items_total": { "type": "integer", "title": "Items Total", "description": "Number of items the job copies" }, "failed_items": { "type": "integer", "title": "Failed Items", "description": "Number of items that could not be copied" }, "waiting_items": { "type": "integer", "title": "Waiting Items", "description": "Number of videos waiting for their proxy before they can be copied. Only used when copying videos as proxies." } }, "type": "object", "required": [ "percent", "items_done", "items_total", "failed_items", "waiting_items" ], "title": "CopyJobProgress", "description": "How far a copy job has got. Each asset and directory counts as one item." }, "CopyJobResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Copy job ID" }, "status": { "$ref": "#/components/schemas/CopyJobStatus", "description": "Status of the job" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label", "description": "Short description of what is being copied: the item's name, or the number of items" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "When the job was started" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Finished At", "description": "When the job completed or failed. Set when `status` is `completed` or `failed`." }, "progress": { "$ref": "#/components/schemas/CopyJobProgress", "description": "How far the job has got" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/CopyJobResult" }, { "type": "null" } ], "description": "The outcome of the job. Set when `status` is `completed`." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Why the job failed. Set when `status` is `failed`." } }, "type": "object", "required": [ "id", "status", "created", "progress" ], "title": "CopyJobResponse", "description": "Status of a copy job." }, "CopyJobResult": { "properties": { "items_skipped": { "type": "boolean", "title": "Items Skipped", "description": "Whether some items, comments, or metadata were left out because you can't access them or they are in the trash" }, "failed_item_details": { "items": { "$ref": "#/components/schemas/CopyJobFailedItem" }, "type": "array", "title": "Failed Item Details", "description": "Items that could not be copied, up to 100" } }, "type": "object", "required": [ "items_skipped", "failed_item_details" ], "title": "CopyJobResult", "description": "The outcome of a completed copy job." }, "CopyJobStatus": { "type": "string", "enum": [ "running", "completed", "failed" ], "title": "CopyJobStatus", "description": "Status of a copy job. A job waiting to start counts as running." }, "DirectoriesRunTarget": { "properties": { "kind": { "type": "string", "const": "directories", "title": "Kind" }, "directory_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "minItems": 1, "title": "Directory IDs", "description": "Directories in the attribute's project; the trash directory is not allowed" }, "recursive": { "type": "boolean", "title": "Recursive", "description": "`true` includes each directory's subdirectories; `false` covers only the assets directly inside it" } }, "type": "object", "required": [ "kind", "directory_ids", "recursive" ], "title": "DirectoriesRunTarget", "description": "Assets in the given directories (`recursive: true` includes their\nsubdirectories), of every type the attribute runs on: the watch and its\nasset-type limit do not apply." }, "DirectoryCreateRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "Name of the directory" }, "auto_rename": { "anyOf": [ { "$ref": "#/components/schemas/AutoRenameStyle" }, { "type": "null" } ], "description": "How to rename the directory when its name is taken. `parenthesized` adds the lowest free number in parentheses, starting at 1: `Photos (1)`. `numeric` adds the lowest free number after a space, starting at 2: `Photos 2`. Without it, a name clash returns `409`." } }, "type": "object", "required": [ "name" ], "title": "DirectoryCreateRequest", "description": "API request schema for creating a directory" }, "DirectoryCreateResponse": { "properties": { "symlink": { "anyOf": [ { "$ref": "#/components/schemas/SymlinkInfo" }, { "type": "null" } ], "description": "Set only on symlinks: items, made by the desktop app or local drive, that point to another asset or directory. Pass a symlink's `id` in `symlink_ids` to move, trash, restore, or copy it; use `symlink.target_id` for everything else." }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Directory ID" }, "name": { "type": "string", "title": "Name", "description": "Directory name" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "ID of the project this directory belongs to" }, "parent_id": { "type": "string", "format": "uuid", "title": "Parent Id", "description": "ID of the parent resource (directory or project)" }, "created_by_user_id": { "type": "string", "format": "uuid", "title": "Created By User Id", "description": "ID of the user that created the directory" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "Creation timestamp" }, "updated": { "type": "string", "format": "date-time", "title": "Updated", "description": "Last update timestamp" }, "content_modified_at": { "type": "string", "format": "date-time", "title": "Content Modified At", "description": "When the directory's contents last changed: a direct child was created, deleted, renamed, or moved in or out" } }, "type": "object", "required": [ "id", "name", "project_id", "parent_id", "created_by_user_id", "created", "updated", "content_modified_at" ], "title": "DirectoryCreateResponse", "description": "API response schema for creating a directory" }, "DirectoryDeleteRequest": { "properties": { "directory_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Directory Ids", "description": "List of directory IDs to delete" } }, "type": "object", "required": [ "directory_ids" ], "title": "DirectoryDeleteRequest", "description": "API request schema for bulk deleting directories" }, "DirectoryDeleteResponse": { "properties": { "deleted_count": { "type": "integer", "title": "Deleted Count", "description": "Number of directories successfully deleted" } }, "type": "object", "required": [ "deleted_count" ], "title": "DirectoryDeleteResponse", "description": "API response schema for bulk deleting directories" }, "DirectoryDetailsResponse": { "properties": { "symlink": { "anyOf": [ { "$ref": "#/components/schemas/SymlinkInfo" }, { "type": "null" } ], "description": "Set only on symlinks: items, made by the desktop app or local drive, that point to another asset or directory. Pass a symlink's `id` in `symlink_ids` to move, trash, restore, or copy it; use `symlink.target_id` for everything else." }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Directory ID" }, "name": { "type": "string", "title": "Name", "description": "Directory name" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "ID of the project this directory belongs to" }, "parent_id": { "type": "string", "format": "uuid", "title": "Parent Id", "description": "ID of the parent resource (directory or project)" }, "created_by_user_id": { "type": "string", "format": "uuid", "title": "Created By User Id", "description": "ID of the user that created the directory" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "Creation timestamp" }, "updated": { "type": "string", "format": "date-time", "title": "Updated", "description": "Last update timestamp" }, "content_modified_at": { "type": "string", "format": "date-time", "title": "Content Modified At", "description": "When the directory's contents last changed: a direct child was created, deleted, renamed, or moved in or out" }, "num_assets": { "type": "integer", "title": "Num Assets", "description": "Total number of assets in directory tree" }, "size_bytes": { "type": "integer", "title": "Size Bytes", "description": "Total size in bytes of all assets in directory tree" }, "duration": { "type": "number", "title": "Duration", "description": "Total duration in seconds of all assets in directory tree" } }, "type": "object", "required": [ "id", "name", "project_id", "parent_id", "created_by_user_id", "created", "updated", "content_modified_at", "num_assets", "size_bytes", "duration" ], "title": "DirectoryDetailsResponse", "description": "API response schema for getting directory details with stats and creator info" }, "DirectoryResponse": { "properties": { "symlink": { "anyOf": [ { "$ref": "#/components/schemas/SymlinkInfo" }, { "type": "null" } ], "description": "Set only on symlinks: items, made by the desktop app or local drive, that point to another asset or directory. Pass a symlink's `id` in `symlink_ids` to move, trash, restore, or copy it; use `symlink.target_id` for everything else." }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Directory ID" }, "name": { "type": "string", "title": "Name", "description": "Directory name" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "ID of the project this directory belongs to" }, "parent_id": { "type": "string", "format": "uuid", "title": "Parent Id", "description": "ID of the parent resource (directory or project)" }, "created_by_user_id": { "type": "string", "format": "uuid", "title": "Created By User Id", "description": "ID of the user that created the directory" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "Creation timestamp" }, "updated": { "type": "string", "format": "date-time", "title": "Updated", "description": "Last update timestamp" }, "content_modified_at": { "type": "string", "format": "date-time", "title": "Content Modified At", "description": "When the directory's contents last changed: a direct child was created, deleted, renamed, or moved in or out" } }, "type": "object", "required": [ "id", "name", "project_id", "parent_id", "created_by_user_id", "created", "updated", "content_modified_at" ], "title": "DirectoryResponse", "description": "API response schema for a directory" }, "DirectoryUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "New name for the directory" } }, "type": "object", "title": "DirectoryUpdateRequest", "description": "API request schema for updating a directory" }, "DirectoryUpdateResponse": { "properties": { "symlink": { "anyOf": [ { "$ref": "#/components/schemas/SymlinkInfo" }, { "type": "null" } ], "description": "Set only on symlinks: items, made by the desktop app or local drive, that point to another asset or directory. Pass a symlink's `id` in `symlink_ids` to move, trash, restore, or copy it; use `symlink.target_id` for everything else." }, "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Directory ID" }, "name": { "type": "string", "title": "Name", "description": "Directory name" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "ID of the project this directory belongs to" }, "parent_id": { "type": "string", "format": "uuid", "title": "Parent Id", "description": "ID of the parent resource (directory or project)" }, "created_by_user_id": { "type": "string", "format": "uuid", "title": "Created By User Id", "description": "ID of the user that created the directory" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "Creation timestamp" }, "updated": { "type": "string", "format": "date-time", "title": "Updated", "description": "Last update timestamp" }, "content_modified_at": { "type": "string", "format": "date-time", "title": "Content Modified At", "description": "When the directory's contents last changed: a direct child was created, deleted, renamed, or moved in or out" } }, "type": "object", "required": [ "id", "name", "project_id", "parent_id", "created_by_user_id", "created", "updated", "content_modified_at" ], "title": "DirectoryUpdateResponse", "description": "API response schema for updating a directory" }, "DownloadVariant": { "type": "string", "enum": [ "original", "stream_proxy", "preview" ], "title": "DownloadVariant", "description": "A file a user can download: the uploaded original, the web-playable stream proxy, or the preview image." }, "ExportFormat": { "type": "string", "enum": [ "vtt", "srt", "txt", "md" ], "title": "ExportFormat", "description": "File format for the exported transcript." }, "Filter": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Attribute ID from `GET /metadata/attributes`." }, "clause": { "$ref": "#/components/schemas/FilterClause", "description": "How to compare the attribute's value with `values`." }, "values": { "items": {}, "type": "array", "title": "Values", "description": "Values to compare with, always a list. Leave it empty for `exists`, `not_exists`, `is_true`, and `is_false`. Select attributes take option IDs, ID types take IDs, and `datetime` takes ISO 8601 strings." } }, "type": "object", "required": [ "id", "clause" ], "title": "Filter", "description": "Filter specification for filtering assets by attribute values." }, "FilterClause": { "type": "string", "enum": [ "eq", "neq", "gt", "lt", "gte", "lte", "contains", "not_contains", "starts_with", "ends_with", "includes", "not_includes", "exists", "not_exists", "is_true", "is_false" ], "title": "FilterClause", "description": "How a filter compares an attribute's value. Each clause works only with the data types listed.\n\n- `eq`: Equals one of the values. `string` (ignores case), `integer`, `float`, `datetime`, `single_select`, `directory_id` (assets directly in the directory).\n- `neq`: Equals none of the values. Same types as `eq`.\n- `gt`: Greater than the value. `integer`, `float`, `datetime`.\n- `lt`: Less than the value. `integer`, `float`, `datetime`.\n- `gte`: Greater than or equal to the value. `integer`, `float`, `datetime`.\n- `lte`: Less than or equal to the value. `integer`, `float`, `datetime`.\n- `contains`: Contains one of the values, ignoring case. `string`.\n- `not_contains`: Contains none of the values, ignoring case. `string`.\n- `starts_with`: Starts with one of the values, ignoring case. `string`.\n- `ends_with`: Ends with one of the values, ignoring case. `string`.\n- `includes`: Has any of the values. `multi_select`, `user_id`, `person_id`, `object_id`, `directory_id` (assets anywhere under the directory).\n- `not_includes`: Has none of the values. Same types as `includes`.\n- `exists`: Has a value. Every type except `boolean` and `directory_id`.\n- `not_exists`: Has no value. Every type except `boolean` and `directory_id`.\n- `is_true`: Is true. `boolean`.\n- `is_false`: Is false. `boolean`.\n\n`neq`, `not_contains`, `not_includes`, and `is_false` also match assets with no value." }, "FsItemsCopyRequest": { "properties": { "asset_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Asset Ids", "description": "List of asset IDs to copy" }, "directory_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Directory Ids", "description": "List of directory IDs to copy (recursively, including all nested items)" }, "symlink_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Symlink Ids", "description": "List of symlink IDs to copy" }, "destination_directory_id": { "type": "string", "format": "uuid", "title": "Destination Directory Id", "description": "ID of the destination parent directory" }, "include_comments": { "type": "boolean", "title": "Include Comments", "description": "Whether comment threads (comments, reactions, mentions, and their attachments) carry over to the copied assets", "default": true }, "include_metadata": { "type": "boolean", "title": "Include Metadata", "description": "Whether metadata values carry over to the copied assets", "default": true }, "copy_as_proxy": { "type": "boolean", "title": "Copy As Proxy", "description": "Copy videos as their stream proxy: the proxy becomes the copied asset's original. Other asset types copy their original.", "default": false } }, "type": "object", "required": [ "destination_directory_id" ], "title": "FsItemsCopyRequest", "description": "API request schema for copying filesystem items into a destination directory.\n\nCopying is asynchronous: the endpoint enqueues a copy job and returns its\njob id, which can be polled via GET /fs-items/copy/{job_id}." }, "FsItemsCopyResponse": { "properties": { "job_id": { "type": "string", "format": "uuid", "title": "Job Id", "description": "ID of the enqueued copy job; poll GET /fs-items/copy/{job_id}" }, "items_total": { "type": "integer", "title": "Items Total", "description": "Number of items the job copies: directories, assets, and symlinks" } }, "type": "object", "required": [ "job_id", "items_total" ], "title": "FsItemsCopyResponse", "description": "API response schema for an enqueued copy job" }, "FsItemsEmptyTrashRequest": { "properties": { "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "Project whose trash to empty" } }, "type": "object", "required": [ "project_id" ], "title": "FsItemsEmptyTrashRequest", "description": "API request schema for permanently deleting all contents of the project trash." }, "FsItemsEmptyTrashResponse": { "properties": { "deleted_asset_count": { "type": "integer", "title": "Deleted Asset Count", "description": "Number of assets permanently deleted from trash" }, "deleted_directory_count": { "type": "integer", "title": "Deleted Directory Count", "description": "Number of directories permanently deleted from trash" }, "deleted_symlink_count": { "type": "integer", "title": "Deleted Symlink Count", "description": "Number of symlinks permanently deleted from trash", "default": 0 } }, "type": "object", "required": [ "deleted_asset_count", "deleted_directory_count" ], "title": "FsItemsEmptyTrashResponse", "description": "API response schema for emptying the project trash" }, "FsItemsMoveRequest": { "properties": { "asset_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Asset Ids", "description": "List of asset IDs to move" }, "directory_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Directory Ids", "description": "List of directory IDs to move" }, "symlink_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Symlink Ids", "description": "List of symlink IDs to move" }, "destination_directory_id": { "type": "string", "format": "uuid", "title": "Destination Directory Id", "description": "ID of the destination parent directory" } }, "type": "object", "required": [ "destination_directory_id" ], "title": "FsItemsMoveRequest", "description": "API request schema for moving filesystem items to a new parent directory" }, "FsItemsMoveResponse": { "properties": { "moved_asset_count": { "type": "integer", "title": "Moved Asset Count", "description": "Number of assets successfully moved" }, "moved_directory_count": { "type": "integer", "title": "Moved Directory Count", "description": "Number of directories successfully moved" }, "moved_symlink_count": { "type": "integer", "title": "Moved Symlink Count", "description": "Number of symlinks successfully moved", "default": 0 } }, "type": "object", "required": [ "moved_asset_count", "moved_directory_count" ], "title": "FsItemsMoveResponse", "description": "API response schema for moving filesystem items" }, "FsItemsMoveToTrashRequest": { "properties": { "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "Project ID the items belong to" }, "asset_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Asset Ids", "description": "List of asset IDs to move to trash" }, "directory_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Directory Ids", "description": "List of directory IDs to move to trash" }, "symlink_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Symlink Ids", "description": "List of symlink IDs to move to trash" } }, "type": "object", "required": [ "project_id" ], "title": "FsItemsMoveToTrashRequest", "description": "API request schema for moving filesystem items to the project trash.\n\nSupply the project_id and the item IDs to trash. Name conflicts in the trash\nare resolved automatically with a parenthesized number." }, "FsItemsRestoreRequest": { "properties": { "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "Project ID the items belong to" }, "asset_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Asset Ids", "description": "List of asset IDs to restore from trash" }, "directory_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Directory Ids", "description": "List of directory IDs to restore from trash" }, "symlink_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Symlink Ids", "description": "List of symlink IDs to restore from trash" } }, "type": "object", "required": [ "project_id" ], "title": "FsItemsRestoreRequest", "description": "API request schema for restoring filesystem items from the project trash.\n\nEach item returns to the directory it was trashed from. If that directory no\nlonger exists or is itself in trash, the item goes to the project root\ndirectory. A name already taken at an item's destination returns 409." }, "FsItemsRestoreResponse": { "properties": { "restored_asset_count": { "type": "integer", "title": "Restored Asset Count", "description": "Number of assets successfully restored" }, "restored_directory_count": { "type": "integer", "title": "Restored Directory Count", "description": "Number of directories successfully restored" }, "restored_symlink_count": { "type": "integer", "title": "Restored Symlink Count", "description": "Number of symlinks successfully restored", "default": 0 } }, "type": "object", "required": [ "restored_asset_count", "restored_directory_count" ], "title": "FsItemsRestoreResponse", "description": "API response schema for restoring filesystem items from trash" }, "GenerationInputSource": { "type": "string", "enum": [ "transcript", "visual" ], "title": "GenerationInputSource", "description": "An input the AI reads when generating a value." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "LinePath": { "properties": { "tool": { "type": "string", "const": "line", "title": "Tool" }, "color": { "type": "string", "title": "Color", "description": "Hex color, such as `#22C55E`" }, "stroke_width": { "type": "number", "title": "Stroke Width", "description": "Line width in screen pixels" }, "start": { "$ref": "#/components/schemas/AnnotationPoint" }, "end": { "$ref": "#/components/schemas/AnnotationPoint" } }, "type": "object", "required": [ "tool", "color", "stroke_width", "start", "end" ], "title": "LinePath", "description": "A straight line from `start` to `end`." }, "ListAssetsRequest": { "properties": { "parent_id": { "type": "string", "format": "uuid", "title": "Parent Id", "description": "Parent directory or project ID" }, "recursive": { "type": "boolean", "title": "Recursive", "description": "When true, include assets from all descendant directories", "default": false }, "filters": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Filter" }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "List of filter objects" }, "sorts": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Sort" }, "type": "array", "maxItems": 3 }, { "type": "null" } ], "title": "Sorts", "description": "List of sorts applied in order" }, "limit": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Limit", "description": "Max results to return", "default": 20 }, "offset": { "type": "integer", "minimum": 0.0, "title": "Offset", "description": "Pagination offset", "default": 0 }, "is_uploaded": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Uploaded", "description": "Filter by upload status" } }, "type": "object", "required": [ "parent_id" ], "title": "ListAssetsRequest", "description": "API request for a filtered asset list." }, "ListCollectionAssetsRequest": { "properties": { "filters": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Filter" }, "type": "array" }, { "type": "null" } ], "title": "Filters", "description": "List of filter objects" }, "sorts": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Sort" }, "type": "array", "maxItems": 3 }, { "type": "null" } ], "title": "Sorts", "description": "List of sorts applied in order" } }, "type": "object", "title": "ListCollectionAssetsRequest", "description": "API request for a filtered collection asset list." }, "ListDirectoriesRequest": { "properties": { "parent_id": { "type": "string", "format": "uuid", "title": "Parent Id", "description": "Directory to list. Only direct children are returned." } }, "type": "object", "required": [ "parent_id" ], "title": "ListDirectoriesRequest", "description": "API request schema for listing directories under a parent" }, "LogicalSignalQuery": { "properties": { "signal": { "$ref": "#/components/schemas/LogicalSignalType", "title": "Signal", "description": "User-facing logical signal type to search" }, "query": { "type": "string", "title": "Query", "description": "Text query for this logical signal type" } }, "additionalProperties": false, "type": "object", "required": [ "signal", "query" ], "title": "LogicalSignalQuery", "description": "One search signal: what to look for and where." }, "LogicalSignalType": { "type": "string", "enum": [ "visual", "transcript", "document", "filename" ], "title": "LogicalSignalType", "description": "Which content a search signal queries.\n\n- `visual`: What's seen.\n- `transcript`: What's said.\n- `document`: Text in documents.\n- `filename`: The file name." }, "MentionCreateData": { "properties": { "user_id": { "type": "string", "format": "uuid", "title": "User Id", "description": "User being mentioned" }, "text": { "type": "string", "title": "Text", "description": "Mention text (e.g., '@John Doe')" }, "start_index": { "type": "integer", "title": "Start Index", "description": "Start position in comment text" }, "end_index": { "type": "integer", "title": "End Index", "description": "End position in comment text (non-inclusive)" } }, "type": "object", "required": [ "user_id", "text", "start_index", "end_index" ], "title": "MentionCreateData", "description": "Data for creating a mention" }, "MentionInfo": { "properties": { "start_index": { "type": "integer", "title": "Start Index", "description": "Start position in comment text" }, "end_index": { "type": "integer", "title": "End Index", "description": "End position in comment text (non-inclusive)" }, "text": { "type": "string", "title": "Text", "description": "Mention text (e.g., '@John Doe')" }, "user": { "$ref": "#/components/schemas/UserInfo", "description": "User being mentioned" } }, "type": "object", "required": [ "start_index", "end_index", "text", "user" ], "title": "MentionInfo", "description": "Mention information with user details" }, "MetadataAttributeCreateRequest": { "properties": { "project_id": { "type": "string", "format": "uuid", "title": "Project ID", "description": "Project the attribute belongs to" }, "name": { "type": "string", "maxLength": 255, "title": "Display Name", "description": "Human-readable name, unique per project" }, "data_type": { "$ref": "#/components/schemas/MetadataDataType", "title": "Data Type", "description": "Type of value this attribute holds" }, "options": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SelectOption" }, "type": "array" }, { "type": "null" } ], "title": "Options", "description": "The choices of a `single_select` or `multi_select` attribute. Not allowed on other data types." }, "generation_config": { "anyOf": [ { "$ref": "#/components/schemas/MetadataGenerationConfig" }, { "type": "null" } ], "title": "Generation Config", "description": "AI generation settings, including the watch" } }, "type": "object", "required": [ "project_id", "name", "data_type" ], "title": "MetadataAttributeCreateRequest", "description": "API request schema for creating a metadata attribute." }, "MetadataAttributeResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Unique identifier for this attribute" }, "project_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Project Id", "description": "Project ID for project-specific attributes, null for system global" }, "name": { "type": "string", "title": "Name", "description": "Human-readable display name" }, "data_type": { "$ref": "#/components/schemas/MetadataDataType", "description": "Type of value this attribute holds" }, "options": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SelectOption" }, "type": "array" }, { "type": "null" } ], "title": "Options", "description": "Available options for select types" }, "source": { "$ref": "#/components/schemas/MetadataSource", "description": "Whether attribute is system-defined or user-created" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Category", "description": "Grouping category for UI display" }, "is_filterable": { "type": "boolean", "title": "Is Filterable", "description": "Whether this attribute can be used in filters" }, "is_editable": { "type": "boolean", "title": "Is Editable", "description": "Whether values for this attribute can be edited through metadata APIs" }, "is_sortable": { "type": "boolean", "title": "Is Sortable", "description": "Whether assets can be sorted by this attribute" }, "generation_config": { "anyOf": [ { "$ref": "#/components/schemas/MetadataGenerationConfig" }, { "type": "null" } ], "description": "AI generation settings; null when generation is off" }, "created_by_user_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Created By User Id", "description": "User who created the attribute; null for system attributes and ones created before creators were recorded" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "When the attribute was created" }, "updated": { "type": "string", "format": "date-time", "title": "Updated", "description": "When the attribute was last updated" } }, "type": "object", "required": [ "id", "name", "data_type", "source", "is_filterable", "is_editable", "is_sortable", "created", "updated" ], "title": "MetadataAttributeResponse", "description": "API response schema for metadata attribute." }, "MetadataAttributeUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Display Name", "description": "Human-readable name, unique per project" }, "options": { "anyOf": [ { "items": { "$ref": "#/components/schemas/SelectOption" }, "type": "array" }, { "type": "null" } ], "title": "Options", "description": "The choices of a `single_select` or `multi_select` attribute. Not allowed on other data types." }, "generation_config": { "anyOf": [ { "$ref": "#/components/schemas/MetadataGenerationConfig" }, { "type": "null" } ], "title": "Generation Config", "description": "AI generation settings. Omit to keep; null turns generation off (existing values are kept)" } }, "type": "object", "title": "MetadataAttributeUpdateRequest", "description": "API request schema for updating a metadata attribute. Omitted and null\nfields are untouched, except `generation_config`: null turns generation off." }, "MetadataDataType": { "type": "string", "enum": [ "string", "integer", "float", "boolean", "datetime", "single_select", "multi_select", "user_id", "person_id", "object_id", "directory_id" ], "title": "MetadataDataType", "description": "Type of value an attribute holds.\n\n- `string`: Text.\n- `integer`: A whole number.\n- `float`: A decimal number.\n- `boolean`: True or false.\n- `datetime`: A date and time.\n- `single_select`: One of the attribute's `options`.\n- `multi_select`: Any number of the attribute's `options`.\n- `user_id`: Users.\n- `person_id`: People recognized in the asset. Used by the built-in People attribute.\n- `object_id`: Objects recognized in the asset. Used by the built-in Objects attribute.\n- `directory_id`: The directories containing the asset. Used by the built-in Path attribute." }, "MetadataGenerationConfig": { "properties": { "prompt": { "type": "string", "maxLength": 8000, "title": "Prompt", "description": "Prompt template; variables like {{transcript}} must match input_sources" }, "input_sources": { "items": { "$ref": "#/components/schemas/GenerationInputSource" }, "type": "array", "minItems": 1, "title": "Input Sources", "description": "Inputs the AI reads when generating a value" }, "watch": { "anyOf": [ { "$ref": "#/components/schemas/Watch" }, { "type": "null" } ], "description": "Watch directories: new assets in them are generated automatically as they finish processing, and a `watch` run covers them. Null means not watching: nothing runs by itself, and a `watch` run is rejected; run on `directories` or `assets` instead" } }, "type": "object", "required": [ "prompt", "input_sources" ], "title": "MetadataGenerationConfig", "description": "Settings for generating an attribute's values with AI." }, "MetadataGenerationStatsResponse": { "properties": { "columns": { "items": { "$ref": "#/components/schemas/CellColumnStats" }, "type": "array", "title": "Columns", "description": "One entry per AI-generated attribute" } }, "type": "object", "required": [ "columns" ], "title": "MetadataGenerationStatsResponse", "description": "API response schema for the per-attribute stats read." }, "MetadataSource": { "type": "string", "enum": [ "system", "user", "asset" ], "title": "MetadataSource", "description": "Source of metadata attribute or value." }, "MetadataValue": { "properties": { "attribute_id": { "type": "string", "format": "uuid", "title": "Attribute Id", "description": "ID of the attribute this value is for" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Display name of the attribute" }, "data_type": { "$ref": "#/components/schemas/MetadataDataType", "description": "Data type of the value" }, "value": { "title": "Value", "description": "The value. Its shape depends on `data_type`:\n\n- `string`: A string.\n- `integer`, `float`: A number.\n- `boolean`: `true` or `false`.\n- `datetime`: An ISO 8601 string.\n- `single_select`: An option ID.\n- `multi_select`: A list of option IDs.\n- `user_id`: A list of users, each with `id`, `first_name`, `last_name`, `email`, and `avatar_url`.\n- `person_id`: A list of people, each with `person_id`, `label`, and `source`.\n- `object_id`: A list of objects, each with `object_id`, `label`, and `source`.\n- `directory_id`: The directories containing the asset, outermost first, each with `id` and `name`. Empty when the asset is directly in the project's top-level directory.\n\n`null` when there's no value." }, "source": { "$ref": "#/components/schemas/CellSource", "description": "Author of the value's current content: user for manual writes, ai for generated ones", "default": "user" } }, "type": "object", "required": [ "attribute_id", "data_type", "value" ], "title": "MetadataValue", "description": "A single metadata value with its attribute." }, "MetadataValueResponse": { "properties": { "attribute_id": { "type": "string", "format": "uuid", "title": "Attribute Id", "description": "ID of the attribute this value is for" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Display name of the attribute" }, "data_type": { "$ref": "#/components/schemas/MetadataDataType", "description": "Data type of the value" }, "value": { "title": "Value", "description": "The value. Its shape depends on `data_type`:\n\n- `string`: A string.\n- `integer`, `float`: A number.\n- `boolean`: `true` or `false`.\n- `datetime`: An ISO 8601 string.\n- `single_select`: An option ID.\n- `multi_select`: A list of option IDs.\n- `user_id`: A list of users, each with `id`, `first_name`, `last_name`, `email`, and `avatar_url`.\n- `person_id`: A list of people, each with `person_id`, `label`, and `source`.\n- `object_id`: A list of objects, each with `object_id`, `label`, and `source`.\n- `directory_id`: The directories containing the asset, outermost first, each with `id` and `name`. Empty when the asset is directly in the project's top-level directory.\n\n`null` when there's no value." }, "source": { "$ref": "#/components/schemas/CellSource", "description": "Author of the value's current content: user for manual writes, ai for generated ones", "default": "user" } }, "type": "object", "required": [ "attribute_id", "data_type", "value" ], "title": "MetadataValueResponse", "description": "API response schema for a single metadata value." }, "MetadataValueSetRequest": { "properties": { "value": { "title": "Value", "description": "The value to set. Its shape depends on the attribute's `data_type`:\n\n- `string`: A string.\n- `integer`, `float`: A number.\n- `boolean`: `true` or `false`.\n- `datetime`: An ISO 8601 string.\n- `single_select`: An option ID.\n- `multi_select`: A list of option IDs.\n- `user_id`: A list of user IDs.\n\nSend `null` to clear the value. Attributes with `is_editable` false can't be set." } }, "type": "object", "required": [ "value" ], "title": "MetadataValueSetRequest", "description": "API request schema for setting a metadata value." }, "PathSegment": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Resource ID" }, "name": { "type": "string", "title": "Name", "description": "Resource name" } }, "type": "object", "required": [ "id", "name" ], "title": "PathSegment", "description": "A segment in a resource path (directory or asset).\nUsed for breadcrumb navigation and path display." }, "PenPath": { "properties": { "tool": { "type": "string", "const": "pen", "title": "Tool" }, "color": { "type": "string", "title": "Color", "description": "Hex color, such as `#22C55E`" }, "stroke_width": { "type": "number", "title": "Stroke Width", "description": "Line width in screen pixels" }, "points": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AnnotationPoint" }, "type": "array" }, { "$ref": "#/components/schemas/CompactPoints" } ], "title": "Points", "description": "Points along the stroke: a list of points, or the same points as two lists" } }, "type": "object", "required": [ "tool", "color", "stroke_width", "points" ], "title": "PenPath", "description": "A freehand stroke." }, "ProjectAddUserRequest": { "properties": { "email": { "type": "string", "title": "Email", "description": "Email of the user to add to project" }, "role": { "$ref": "#/components/schemas/ProjectRole", "description": "`no_access` is only for workspace Members, to block them from this project.", "default": "editor" }, "purchase_seat": { "type": "boolean", "title": "Purchase Seat", "description": "Buy a seat if none is free (prorated, charged now). Ignored when a seat is free. Only when the person is new to the workspace and you're a workspace admin.", "default": false } }, "type": "object", "required": [ "email" ], "title": "ProjectAddUserRequest", "description": "Add a person to a project. If the email has no Aspect account yet, the person is invited." }, "ProjectCreateRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "Name of the project" }, "default_role": { "$ref": "#/components/schemas/ProjectRole", "description": "Default role for workspace members accessing this project (full_access, editor, commenter, downloader, viewer, no_access)", "default": "full_access" } }, "type": "object", "required": [ "name" ], "title": "ProjectCreateRequest", "description": "API request schema for creating a project" }, "ProjectCreateResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Project ID" }, "name": { "type": "string", "title": "Name", "description": "Project name" }, "root_directory_id": { "type": "string", "format": "uuid", "title": "Root Directory Id", "description": "The project's top-level directory. Use it as `parent_id` to list the project's contents." }, "trash_directory_id": { "type": "string", "format": "uuid", "title": "Trash Directory Id", "description": "Trash directory ID - deleted assets are moved here" }, "default_role": { "$ref": "#/components/schemas/ProjectRole", "description": "Default role for workspace members accessing this project" }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether the project is active. Inactive projects are hidden from listing and discovery surfaces." }, "num_assets": { "type": "integer", "title": "Num Assets", "description": "Number of assets in project" }, "size_bytes": { "type": "integer", "title": "Size Bytes", "description": "Total size of assets in bytes" }, "duration": { "type": "number", "title": "Duration", "description": "Total duration in seconds" }, "created_by_user_id": { "type": "string", "format": "uuid", "title": "Created By User Id", "description": "ID of the user that created the project" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "Creation timestamp" }, "updated": { "type": "string", "format": "date-time", "title": "Updated", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "name", "root_directory_id", "trash_directory_id", "default_role", "is_active", "num_assets", "size_bytes", "duration", "created_by_user_id", "created", "updated" ], "title": "ProjectCreateResponse", "description": "API response schema for creating a project" }, "ProjectResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Project ID" }, "name": { "type": "string", "title": "Name", "description": "Project name" }, "root_directory_id": { "type": "string", "format": "uuid", "title": "Root Directory Id", "description": "The project's top-level directory. Use it as `parent_id` to list the project's contents." }, "trash_directory_id": { "type": "string", "format": "uuid", "title": "Trash Directory Id", "description": "Trash directory ID - deleted assets are moved here" }, "default_role": { "$ref": "#/components/schemas/ProjectRole", "description": "Default role for workspace members accessing this project" }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether the project is active. Inactive projects are hidden from listing and discovery surfaces." }, "num_assets": { "type": "integer", "title": "Num Assets", "description": "Number of assets in project" }, "size_bytes": { "type": "integer", "title": "Size Bytes", "description": "Total size of assets in bytes" }, "duration": { "type": "number", "title": "Duration", "description": "Total duration in seconds" }, "created_by_user_id": { "type": "string", "format": "uuid", "title": "Created By User Id", "description": "ID of the user that created the project" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "Creation timestamp" }, "updated": { "type": "string", "format": "date-time", "title": "Updated", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "name", "root_directory_id", "trash_directory_id", "default_role", "is_active", "num_assets", "size_bytes", "duration", "created_by_user_id", "created", "updated" ], "title": "ProjectResponse", "description": "API response schema for a project" }, "ProjectRole": { "type": "string", "enum": [ "full_access", "editor", "commenter", "downloader", "viewer", "no_access" ], "title": "ProjectRole", "description": "Role on a project." }, "ProjectShareListResponse": { "properties": { "shares": { "items": { "$ref": "#/components/schemas/ProjectShareResponse" }, "type": "array", "title": "Shares", "description": "List of shares in the project" }, "total": { "type": "integer", "title": "Total", "description": "Total number of shares in the project" } }, "type": "object", "required": [ "shares", "total" ], "title": "ProjectShareListResponse", "description": "API response schema for listing shares within a project" }, "ProjectShareResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Share ID (used in URLs)" }, "resource_id": { "type": "string", "format": "uuid", "title": "Resource Id", "description": "Resource being shared" }, "resource_type": { "$ref": "#/components/schemas/ResourceType", "description": "`asset`, `directory`, or `collection`" }, "resource_name": { "type": "string", "title": "Resource Name", "description": "Name of the resource" }, "created_by_user_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Created By User Id", "description": "User who created the share. Null when that account has been deleted" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Share name" }, "actions": { "type": "integer", "title": "Actions", "description": "Allowed actions bitmap" }, "has_password": { "type": "boolean", "title": "Has Password", "description": "Whether share is password protected" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "Expiration timestamp" }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether the share is active" }, "watermark_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Watermark Id", "description": "Watermark configuration applied to share viewers" }, "visible_metadata_attribute_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Visible Metadata Attribute Ids", "description": "Metadata attribute IDs share users can see" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "Creation timestamp" }, "updated": { "type": "string", "format": "date-time", "title": "Updated", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "resource_id", "resource_type", "resource_name", "actions", "has_password", "is_active", "created", "updated" ], "title": "ProjectShareResponse", "description": "API response schema for a share in the project share list (includes resource data)" }, "ProjectStatusFilter": { "type": "string", "enum": [ "active", "inactive", "all" ], "title": "ProjectStatusFilter", "description": "Filter for project listings by active status." }, "ProjectUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "New name for the project" }, "default_role": { "anyOf": [ { "$ref": "#/components/schemas/ProjectRole" }, { "type": "null" } ], "description": "New default role for workspace members (full_access, editor, commenter, downloader, viewer, no_access)" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active", "description": "New active status for the project (requires workspace admin access). Inactive projects are hidden from listing and discovery surfaces." } }, "type": "object", "title": "ProjectUpdateRequest", "description": "API request schema for updating a project" }, "ProjectUpdateResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Project ID" }, "name": { "type": "string", "title": "Name", "description": "Project name" }, "root_directory_id": { "type": "string", "format": "uuid", "title": "Root Directory Id", "description": "The project's top-level directory. Use it as `parent_id` to list the project's contents." }, "trash_directory_id": { "type": "string", "format": "uuid", "title": "Trash Directory Id", "description": "Trash directory ID - deleted assets are moved here" }, "default_role": { "$ref": "#/components/schemas/ProjectRole", "description": "Default role for workspace members accessing this project" }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether the project is active. Inactive projects are hidden from listing and discovery surfaces." }, "num_assets": { "type": "integer", "title": "Num Assets", "description": "Number of assets in project" }, "size_bytes": { "type": "integer", "title": "Size Bytes", "description": "Total size of assets in bytes" }, "duration": { "type": "number", "title": "Duration", "description": "Total duration in seconds" }, "created_by_user_id": { "type": "string", "format": "uuid", "title": "Created By User Id", "description": "ID of the user that created the project" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "Creation timestamp" }, "updated": { "type": "string", "format": "date-time", "title": "Updated", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "name", "root_directory_id", "trash_directory_id", "default_role", "is_active", "num_assets", "size_bytes", "duration", "created_by_user_id", "created", "updated" ], "title": "ProjectUpdateResponse", "description": "API response schema for updating a project" }, "ProjectUpdateRoleRequest": { "properties": { "role": { "$ref": "#/components/schemas/ProjectRole", "description": "Setting a Limited Member's last project to `no_access` removes them from the workspace." } }, "type": "object", "required": [ "role" ], "title": "ProjectUpdateRoleRequest", "description": "Change a person's role on a project." }, "ProjectUserResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "User ID" }, "first_name": { "type": "string", "title": "First Name", "description": "User's first name" }, "last_name": { "type": "string", "title": "Last Name", "description": "User's last name" }, "email": { "type": "string", "title": "Email", "description": "User's email address" }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar Url", "description": "User's avatar URL" }, "role": { "$ref": "#/components/schemas/ProjectRole", "description": "User's effective role on this project" }, "workspace_role": { "$ref": "#/components/schemas/WorkspaceRole", "description": "User's workspace role" }, "has_explicit_permission": { "type": "boolean", "title": "Has Explicit Permission", "description": "True when the role was set on this project directly. False when it comes from the project's default role or workspace ownership." } }, "type": "object", "required": [ "id", "first_name", "last_name", "email", "role", "workspace_role", "has_explicit_permission" ], "title": "ProjectUserResponse", "description": "API response schema for a user with project access." }, "PublicShareOEmbedResponse": { "properties": { "version": { "type": "string", "title": "Version", "description": "oEmbed protocol version", "default": "1.0" }, "type": { "type": "string", "title": "Type", "description": "oEmbed resource type (video or rich)" }, "title": { "type": "string", "title": "Title", "description": "Name of the shared asset" }, "provider_name": { "type": "string", "title": "Provider Name", "description": "Display name of the embed provider" }, "provider_url": { "type": "string", "title": "Provider Url", "description": "Base URL of the embed provider" }, "width": { "type": "integer", "title": "Width", "description": "Width in pixels of the embed html" }, "height": { "type": "integer", "title": "Height", "description": "Height in pixels of the embed html" }, "html": { "type": "string", "title": "Html", "description": "Iframe markup that renders the embed" } }, "type": "object", "required": [ "type", "title", "provider_name", "provider_url", "width", "height", "html" ], "title": "PublicShareOEmbedResponse", "description": "oEmbed (https://oembed.com) response describing how to embed a share URL." }, "ReactionAddRequest": { "properties": { "reaction": { "type": "string", "title": "Reaction", "description": "An emoji, such as \ud83d\udc4d." } }, "type": "object", "required": [ "reaction" ], "title": "ReactionAddRequest", "description": "API request schema for adding a reaction" }, "ReactionGroup": { "properties": { "reaction": { "type": "string", "title": "Reaction", "description": "An emoji, such as \ud83d\udc4d." }, "users": { "items": { "$ref": "#/components/schemas/UserInfo" }, "type": "array", "title": "Users", "description": "Users who added this reaction" } }, "type": "object", "required": [ "reaction", "users" ], "title": "ReactionGroup", "description": "Grouped reactions by reaction type" }, "RemoveFromVersionStackRequest": { "properties": { "asset_id": { "type": "string", "format": "uuid", "title": "Asset Id", "description": "ID of the asset to remove from its version stack" } }, "type": "object", "required": [ "asset_id" ], "title": "RemoveFromVersionStackRequest", "description": "API request to remove an asset from its version stack" }, "RemoveFromVersionStackResponse": { "properties": { "stack_dissolved": { "type": "boolean", "title": "Stack Dissolved", "description": "True if only one asset was left, so the stack was dissolved" } }, "type": "object", "required": [ "stack_dissolved" ], "title": "RemoveFromVersionStackResponse", "description": "API response for removing an asset from its version stack" }, "ReorderVersionStackRequest": { "properties": { "version_stack_id": { "type": "string", "format": "uuid", "title": "Version Stack Id", "description": "ID of the version stack to reorder" }, "ordered_asset_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "title": "Ordered Asset Ids", "description": "Ordered list of asset IDs. Position 0 = version 1 (bottom), last = top version." } }, "type": "object", "required": [ "version_stack_id", "ordered_asset_ids" ], "title": "ReorderVersionStackRequest", "description": "API request to reorder assets within a version stack" }, "ResourceType": { "type": "string", "enum": [ "workspace", "project", "directory", "asset", "symlink", "collection", "canvas" ], "title": "ResourceType", "description": "Types of resources in the hierarchy." }, "SearchAssetMetadata": { "properties": { "moments": { "items": { "$ref": "#/components/schemas/SearchMoment" }, "type": "array", "title": "Moments", "description": "Where in the asset the search matched" }, "confidence": { "$ref": "#/components/schemas/ConfidenceRating", "title": "Confidence", "description": "How strong the asset's best match is" } }, "type": "object", "required": [ "confidence" ], "title": "SearchAssetMetadata", "description": "How an asset matched the search." }, "SearchAssetResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "type": { "$ref": "#/components/schemas/AssetType", "description": "Type of the asset (video, image, etc)" }, "name": { "type": "string", "title": "Name" }, "size_bytes": { "type": "integer", "title": "Size Bytes" }, "media": { "$ref": "#/components/schemas/AssetMedia", "description": "Intrinsic media properties (dimensions, duration, frame rate, timecode, page count)" }, "mime_type": { "type": "string", "title": "Mime Type" }, "is_uploaded": { "type": "boolean", "title": "Is Uploaded" }, "is_generated": { "type": "boolean", "title": "Is Generated", "description": "Whether this asset was produced by the AI generation pipeline", "default": false }, "workspace_id": { "type": "string", "format": "uuid", "title": "Workspace Id", "description": "ID of the workspace this asset belongs to" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id", "description": "ID of the project this asset belongs to" }, "parent_id": { "type": "string", "format": "uuid", "title": "Parent Id", "description": "ID of the parent resource (directory or project)" }, "comment_count": { "type": "integer", "title": "Comment Count", "description": "Total number of visible comments on this asset, including replies" }, "created_by_user_id": { "type": "string", "format": "uuid", "title": "Created By User Id", "description": "ID of the user that created the asset" }, "version_stack_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Version Stack Id", "description": "Version stack ID. Null if the asset isn't in a stack." }, "version_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Version Number", "description": "Position in the version stack, starting at 1. Null if the asset isn't in a stack." }, "is_top_version": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Top Version", "description": "True for the top version of a stack. Null if the asset isn't in a stack." }, "manifest_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Manifest Id", "description": "ID of the asset's current file content. It changes whenever the content changes. Null when the asset has no content yet." }, "created": { "type": "string", "format": "date-time", "title": "Created" }, "updated": { "type": "string", "format": "date-time", "title": "Updated" }, "content_modified_at": { "type": "string", "format": "date-time", "title": "Content Modified At", "description": "When the asset's file content last changed. Renames and metadata edits don't change it." }, "search": { "$ref": "#/components/schemas/SearchAssetMetadata", "title": "Search", "description": "How the asset matched the search" } }, "type": "object", "required": [ "id", "type", "name", "size_bytes", "mime_type", "is_uploaded", "workspace_id", "project_id", "parent_id", "comment_count", "created_by_user_id", "created", "updated", "content_modified_at", "search" ], "title": "SearchAssetResponse", "description": "An asset that matched the search, with the match details in `search`." }, "SearchEvidenceText": { "properties": { "excerpt": { "type": "string", "title": "Excerpt", "description": "A short excerpt of the matching text" } }, "type": "object", "required": [ "excerpt" ], "title": "SearchEvidenceText", "description": "Text that matched the search." }, "SearchMoment": { "properties": { "kind": { "$ref": "#/components/schemas/SearchMomentKind", "title": "Kind", "description": "What matched" }, "start_time": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Start Time", "description": "Start of the match in seconds, for video and audio" }, "end_time": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "End Time", "description": "End of the match in seconds, for video and audio" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page", "description": "Page number, starting at 1, for document matches" }, "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query", "description": "The query that matched" }, "evidence_text": { "anyOf": [ { "$ref": "#/components/schemas/SearchEvidenceText" }, { "type": "null" } ], "title": "Evidence Text", "description": "The matching text, for transcript and document matches" } }, "type": "object", "required": [ "kind" ], "title": "SearchMoment", "description": "A place in the asset that matched the search. Moments without a time or page match the asset as a whole." }, "SearchMomentKind": { "type": "string", "enum": [ "visual", "transcript", "document", "filename" ], "title": "SearchMomentKind", "description": "What a search matched." }, "SearchRequest": { "properties": { "project_id": { "type": "string", "format": "uuid", "title": "Project ID", "description": "ID of the project to search within" }, "spec": { "$ref": "#/components/schemas/UserSearchSpec", "title": "Spec", "description": "What to search for and how to filter. Needs at least one signal or filter." }, "limit": { "type": "integer", "maximum": 100.0, "minimum": 1.0, "title": "Limit", "description": "Maximum number of assets to return.", "default": 50 }, "offset": { "type": "integer", "minimum": 0.0, "title": "Offset", "description": "Number of matching assets to skip. Only the first 1000 matching assets are returned; a page past them is empty.", "default": 0 } }, "additionalProperties": false, "type": "object", "required": [ "project_id", "spec" ], "title": "SearchRequest", "description": "API request schema for end-user project search." }, "SearchResponse": { "properties": { "assets": { "items": { "$ref": "#/components/schemas/SearchAssetResponse" }, "type": "array", "title": "Search Results", "description": "Matching assets, best match first; a search with only filters sorts them by name." }, "has_more": { "type": "boolean", "title": "Has More", "description": "Whether more matching assets follow this page; a page can be short even when they do. To get them, send the same request with `offset` increased by `limit`." } }, "type": "object", "required": [ "assets", "has_more" ], "title": "SearchResponse", "description": "Top-level response for project search." }, "SelectOption": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "label": { "type": "string", "title": "Label" }, "archived": { "type": "boolean", "title": "Archived", "default": false } }, "type": "object", "required": [ "label" ], "title": "SelectOption", "description": "Option for single_select/multi_select types." }, "ShareCreateRequest": { "properties": { "resource_id": { "type": "string", "format": "uuid", "title": "Resource Id", "description": "Resource being shared" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "User-friendly name for the share" }, "actions": { "type": "integer", "title": "Actions", "description": "Bitmap of allowed actions (VIEW=1, EDIT=2)" }, "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Password", "description": "Optional password for share protection" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "Optional expiration timestamp" }, "watermark_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Watermark Id", "description": "Watermark configuration to apply to share viewers" }, "visible_metadata_attribute_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Visible Metadata Attribute Ids", "description": "Metadata attribute IDs share users can see (everything else is hidden)" } }, "type": "object", "required": [ "resource_id", "actions" ], "title": "ShareCreateRequest", "description": "API request schema for creating a share" }, "ShareListResponse": { "properties": { "shares": { "items": { "$ref": "#/components/schemas/ShareResponse" }, "type": "array", "title": "Shares", "description": "List of shares" }, "total": { "type": "integer", "title": "Total", "description": "Total number of shares for the resource" } }, "type": "object", "required": [ "shares", "total" ], "title": "ShareListResponse", "description": "API response schema for listing shares" }, "SharePasswordResponse": { "properties": { "password": { "type": "string", "title": "Password", "description": "Current decrypted share password" } }, "type": "object", "required": [ "password" ], "title": "SharePasswordResponse", "description": "API response schema for revealing a share password to an authorized user." }, "ShareResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Share ID (used in URLs)" }, "resource_id": { "type": "string", "format": "uuid", "title": "Resource Id", "description": "Resource being shared" }, "resource_type": { "$ref": "#/components/schemas/ResourceType", "description": "`asset`, `directory`, or `collection`" }, "resource_name": { "type": "string", "title": "Resource Name", "description": "Name of the resource" }, "created_by_user_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Created By User Id", "description": "User who created the share. Null when that account has been deleted" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Share name" }, "actions": { "type": "integer", "title": "Actions", "description": "Allowed actions bitmap" }, "has_password": { "type": "boolean", "title": "Has Password", "description": "Whether share is password protected" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "Expiration timestamp" }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether the share is active" }, "watermark_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Watermark Id", "description": "Watermark configuration applied to share viewers" }, "visible_metadata_attribute_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Visible Metadata Attribute Ids", "description": "Metadata attribute IDs share users can see" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "Creation timestamp" }, "updated": { "type": "string", "format": "date-time", "title": "Updated", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "resource_id", "resource_type", "resource_name", "actions", "has_password", "is_active", "created", "updated" ], "title": "ShareResponse", "description": "API response schema for a share" }, "ShareTemplateCreateRequest": { "properties": { "workspace_id": { "type": "string", "format": "uuid", "title": "Workspace Id", "description": "Workspace to create the share template in" }, "name": { "type": "string", "title": "Name", "description": "Display name for the share template" }, "actions": { "type": "integer", "title": "Actions", "description": "Bitmap of allowed actions (VIEW=1, EDIT=2)" } }, "type": "object", "required": [ "workspace_id", "name", "actions" ], "title": "ShareTemplateCreateRequest", "description": "API request schema for creating a share template" }, "ShareTemplateResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Share template ID" }, "workspace_id": { "type": "string", "format": "uuid", "title": "Workspace Id", "description": "Workspace ID" }, "name": { "type": "string", "title": "Name", "description": "Display name" }, "actions": { "type": "integer", "title": "Actions", "description": "Allowed actions bitmap" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "Creation timestamp" }, "updated": { "type": "string", "format": "date-time", "title": "Updated", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "workspace_id", "name", "actions", "created", "updated" ], "title": "ShareTemplateResponse", "description": "API response schema for a share template" }, "ShareTemplateUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "New display name for the share template" }, "actions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Actions", "description": "New actions bitmap" } }, "type": "object", "title": "ShareTemplateUpdateRequest", "description": "API request schema for updating a share template" }, "ShareUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "New name for the share" }, "actions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Actions", "description": "New actions bitmap" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active", "description": "Whether the share is active" }, "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Password", "description": "New password. Omit to keep the current value." }, "clear_password": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Clear Password", "description": "Set to true to remove password" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "New expiration. Omit to keep the current value." }, "clear_expires_at": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Clear Expires At", "description": "Set to true to remove expiration" }, "watermark_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Watermark Id", "description": "Watermark configuration to apply to share viewers" }, "clear_watermark": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Clear Watermark", "description": "Set to true to remove watermark from share" }, "visible_metadata_attribute_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Visible Metadata Attribute Ids", "description": "Metadata attribute IDs share users can see, everything else is hidden (empty array clears)" } }, "type": "object", "title": "ShareUpdateRequest", "description": "API request schema for updating a share" }, "SignedAttachment": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Resource identifier" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "Temporary download URL" }, "url_expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Url Expires At", "description": "When the URL expires" }, "filename": { "type": "string", "title": "Filename", "description": "Original filename" }, "mime_type": { "type": "string", "title": "Mime Type", "description": "MIME type of the file" }, "size_bytes": { "type": "integer", "title": "Size Bytes", "description": "File size in bytes" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "Created timestamp" } }, "type": "object", "required": [ "id", "filename", "mime_type", "size_bytes", "created" ], "title": "SignedAttachment", "description": "An attachment with a temporary download URL; url and url_expires_at are null until the upload is confirmed." }, "Sort": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "UUID of the attribute to sort by" }, "order": { "$ref": "#/components/schemas/SortOrder", "description": "Sort direction (asc or desc)", "default": "asc" } }, "type": "object", "required": [ "id" ], "title": "Sort", "description": "Sort specification for ordering results." }, "SortOrder": { "type": "string", "enum": [ "asc", "desc" ], "title": "SortOrder", "description": "Sort direction." }, "SymlinkInfo": { "properties": { "target_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Target Id", "description": "ID of the asset or directory the symlink points to. Null when it can't be followed; `status` says why." }, "status": { "$ref": "#/components/schemas/SymlinkResolutionStatus", "description": "`resolved`: the target was found. `dangling`: the target was moved or deleted. `permission_denied`: you can't view the target. `external`: the symlink points to a file outside Aspect." } }, "type": "object", "required": [ "status" ], "title": "SymlinkInfo", "description": "Where a symlink points." }, "SymlinkResolutionStatus": { "type": "string", "enum": [ "resolved", "dangling", "permission_denied", "external" ], "title": "SymlinkResolutionStatus" }, "TextHighlight": { "properties": { "text": { "type": "string", "title": "Text", "description": "The highlighted text" }, "rects": { "items": { "$ref": "#/components/schemas/TextHighlightRect" }, "type": "array", "title": "Rects", "description": "Rectangles covering the highlighted text on the page" } }, "type": "object", "required": [ "text", "rects" ], "title": "TextHighlight", "description": "Text highlighted on a document page." }, "TextHighlightRect": { "properties": { "x": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "X", "description": "Left edge, from 0 to 1" }, "y": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Y", "description": "Top edge, from 0 to 1" }, "width": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Width", "description": "Width, from 0 to 1" }, "height": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Height", "description": "Height, from 0 to 1" } }, "type": "object", "required": [ "x", "y", "width", "height" ], "title": "TextHighlightRect", "description": "A rectangle on a document page, as fractions of the page size." }, "TranscriptionParagraph": { "properties": { "text": { "type": "string", "title": "Text", "description": "Paragraph text" }, "start_time": { "type": "number", "title": "Start Time", "description": "Start time in seconds" }, "end_time": { "type": "number", "title": "End Time", "description": "End time in seconds" }, "speaker": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker", "description": "Speaker number, starting at 0. The same number is the same voice within this asset." } }, "type": "object", "required": [ "text", "start_time", "end_time" ], "title": "TranscriptionParagraph", "description": "One transcript paragraph." }, "TranscriptionResponse": { "properties": { "paragraphs": { "items": { "$ref": "#/components/schemas/TranscriptionParagraph" }, "type": "array", "title": "Paragraphs", "description": "Transcription paragraph boundaries" }, "words": { "items": { "$ref": "#/components/schemas/TranscriptionWord" }, "type": "array", "title": "Words", "description": "Detailed transcription words" } }, "type": "object", "title": "TranscriptionResponse", "description": "Response model for transcription data" }, "TranscriptionWord": { "properties": { "text": { "type": "string", "title": "Text", "description": "Word text" }, "start_time": { "type": "number", "title": "Start Time", "description": "Start time in seconds" }, "end_time": { "type": "number", "title": "End Time", "description": "End time in seconds" }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Confidence", "description": "Confidence score between 0.0 and 1.0" }, "speaker": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Speaker", "description": "Speaker number, starting at 0. The same number is the same voice within this asset." } }, "type": "object", "required": [ "text", "start_time", "end_time" ], "title": "TranscriptionWord", "description": "One transcribed word." }, "UserInfo": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "User ID" }, "first_name": { "type": "string", "title": "First Name", "description": "User's first name" }, "last_name": { "type": "string", "title": "Last Name", "description": "User's last name" }, "email": { "type": "string", "title": "Email", "description": "User's email address" }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar Url", "description": "User's avatar URL" } }, "type": "object", "required": [ "id", "first_name", "last_name", "email" ], "title": "UserInfo", "description": "Lightweight user information for API responses" }, "UserResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "first_name": { "type": "string", "title": "First Name" }, "last_name": { "type": "string", "title": "Last Name" }, "email": { "type": "string", "title": "Email" }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar Url" }, "created": { "type": "string", "format": "date-time", "title": "Created" }, "updated": { "type": "string", "format": "date-time", "title": "Updated" } }, "type": "object", "required": [ "id", "first_name", "last_name", "email", "avatar_url", "created", "updated" ], "title": "UserResponse", "description": "API Response model for user information" }, "UserSearchSpec": { "properties": { "signals": { "items": { "$ref": "#/components/schemas/LogicalSignalQuery" }, "type": "array", "title": "Signals", "description": "Text queries to run, each against one kind of content" }, "filters": { "items": { "$ref": "#/components/schemas/Filter" }, "type": "array", "title": "Filters", "description": "Filters to apply to search results" } }, "additionalProperties": false, "type": "object", "required": [ "signals" ], "title": "UserSearchSpec", "description": "What to search for and how to filter." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VersionStackResponse": { "properties": { "version_stack_id": { "type": "string", "format": "uuid", "title": "Version Stack Id", "description": "ID of the version stack" }, "assets": { "items": { "$ref": "#/components/schemas/AssetResponse" }, "type": "array", "title": "Assets", "description": "Assets in the stack, ordered from highest version number to lowest" } }, "type": "object", "required": [ "version_stack_id", "assets" ], "title": "VersionStackResponse", "description": "API response containing a full version stack" }, "Watch": { "properties": { "resource_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "minItems": 1, "title": "Resource Ids", "description": "Directories whose assets are watched. Use the project's root_directory_id for the whole project" }, "asset_types": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AssetType" }, "type": "array" }, { "type": "null" } ], "title": "Asset Types", "description": "Limit to these asset types; null means every compatible type" } }, "type": "object", "required": [ "resource_ids" ], "title": "Watch", "description": "Directories an attribute watches, with an optional asset-type limit.\nNew assets in them are generated automatically as they finish processing,\nand a `watch` run covers them. The trash directory isn't allowed, and a\ndeleted directory stops matching." }, "WatchRunTarget": { "properties": { "kind": { "type": "string", "const": "watch", "title": "Kind" } }, "type": "object", "required": [ "kind" ], "title": "WatchRunTarget", "description": "Every asset the attribute watches; rejected when it watches nothing." }, "WatermarkConfig": { "properties": { "text_pattern": { "type": "string", "title": "Text Pattern", "description": "Text with variable placeholders ({viewer_email}, {viewer_name}, {timestamp}, {workspace_name}), supports newlines" }, "position_x": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Position X", "description": "Horizontal position (0.0 = left, 1.0 = right)" }, "position_y": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Position Y", "description": "Vertical position (0.0 = top, 1.0 = bottom)" }, "text_color": { "type": "string", "title": "Text Color", "description": "Hex color code for watermark text", "default": "#FFFFFF" }, "alpha": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Alpha", "description": "Opacity (0.0 = invisible, 1.0 = fully opaque)", "default": 1.0 }, "font_size": { "$ref": "#/components/schemas/WatermarkFontSize", "description": "Font size for watermark text", "default": "medium" }, "font_weight": { "$ref": "#/components/schemas/WatermarkFontWeight", "description": "Font weight for watermark text", "default": "normal" }, "rotation": { "type": "number", "maximum": 180.0, "minimum": -180.0, "title": "Rotation", "description": "Clockwise rotation in degrees.", "default": 0.0 } }, "type": "object", "required": [ "text_pattern", "position_x", "position_y" ], "title": "WatermarkConfig", "description": "Visual configuration for watermark text overlay." }, "WatermarkCreateRequest": { "properties": { "workspace_id": { "type": "string", "format": "uuid", "title": "Workspace Id", "description": "Workspace to create the watermark in" }, "name": { "type": "string", "title": "Name", "description": "Display name for the watermark (e.g., 'Default', 'External Review')" }, "config": { "$ref": "#/components/schemas/WatermarkConfig", "description": "Visual configuration for the watermark overlay" } }, "type": "object", "required": [ "workspace_id", "name", "config" ], "title": "WatermarkCreateRequest", "description": "API request schema for creating a watermark" }, "WatermarkFontSize": { "type": "string", "enum": [ "small", "medium", "large" ], "title": "WatermarkFontSize", "description": "Font size options for watermark text overlay" }, "WatermarkFontWeight": { "type": "string", "enum": [ "light", "normal", "bold" ], "title": "WatermarkFontWeight", "description": "Font weight options for watermark text overlay" }, "WatermarkResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Watermark ID" }, "workspace_id": { "type": "string", "format": "uuid", "title": "Workspace Id", "description": "Workspace ID" }, "name": { "type": "string", "title": "Name", "description": "Display name" }, "config": { "$ref": "#/components/schemas/WatermarkConfig", "description": "Visual configuration" }, "active_share_count": { "type": "integer", "title": "Active Share Count", "description": "Number of shares currently using this watermark", "default": 0 }, "created_by_user_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Created By User Id", "description": "User who created this watermark. Null when that account has been deleted" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "Creation timestamp" }, "updated": { "type": "string", "format": "date-time", "title": "Updated", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "workspace_id", "name", "config", "created_by_user_id", "created", "updated" ], "title": "WatermarkResponse", "description": "API response schema for a watermark" }, "WatermarkUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "New display name for the watermark" }, "config": { "anyOf": [ { "$ref": "#/components/schemas/WatermarkConfig" }, { "type": "null" } ], "description": "Updated visual configuration" } }, "type": "object", "title": "WatermarkUpdateRequest", "description": "API request schema for updating a watermark" }, "WorkspaceAddUserRequest": { "properties": { "email": { "type": "string", "title": "Email", "description": "Email of the user to add to workspace" }, "role": { "$ref": "#/components/schemas/WorkspaceRole", "description": "Role to assign to the user (must be a workspace role: owner, member, member_limited)", "default": "member" }, "purchase_seat": { "type": "boolean", "title": "Purchase Seat", "description": "Buy a seat if none is free (prorated, charged now). Ignored when a seat is free.", "default": false } }, "type": "object", "required": [ "email" ], "title": "WorkspaceAddUserRequest", "description": "Add a person to a workspace. If the email has no Aspect account yet, the person is invited." }, "WorkspaceCreateRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "Name of the workspace" } }, "type": "object", "required": [ "name" ], "title": "WorkspaceCreateRequest", "description": "API request schema for creating a workspace" }, "WorkspaceResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Workspace ID" }, "name": { "type": "string", "title": "Name", "description": "Workspace name" }, "created_by_user_id": { "type": "string", "format": "uuid", "title": "Created By User Id", "description": "ID of the user that created the workspace" }, "created": { "type": "string", "format": "date-time", "title": "Created", "description": "Creation timestamp" }, "updated": { "type": "string", "format": "date-time", "title": "Updated", "description": "Last update timestamp" } }, "type": "object", "required": [ "id", "name", "created_by_user_id", "created", "updated" ], "title": "WorkspaceResponse", "description": "API response schema for a workspace" }, "WorkspaceRole": { "type": "string", "enum": [ "owner", "member", "member_limited" ], "title": "WorkspaceRole", "description": "Role in a workspace." }, "WorkspaceUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "New name for the workspace" } }, "type": "object", "title": "WorkspaceUpdateRequest", "description": "API request schema for updating a workspace" }, "WorkspaceUpdateRoleRequest": { "properties": { "role": { "$ref": "#/components/schemas/WorkspaceRole", "description": "New role for the user (must be a workspace role: owner, member, member_limited)" } }, "type": "object", "required": [ "role" ], "title": "WorkspaceUpdateRoleRequest", "description": "Change a member's workspace role. A Limited Member keeps only the projects they were added to." }, "WorkspaceUserResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "User ID" }, "first_name": { "type": "string", "title": "First Name", "description": "User's first name" }, "last_name": { "type": "string", "title": "Last Name", "description": "User's last name" }, "email": { "type": "string", "title": "Email", "description": "User's email address" }, "avatar_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Avatar Url", "description": "User's avatar URL" }, "role": { "$ref": "#/components/schemas/WorkspaceRole", "description": "User's workspace role" } }, "type": "object", "required": [ "id", "first_name", "last_name", "email", "role" ], "title": "WorkspaceUserResponse", "description": "API response schema for a workspace user." } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Aspect API key (sk_...) in Authorization header. 'Bearer ' optional." } } }, "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Users" }, { "name": "API Keys" }, { "name": "Workspaces" }, { "name": "Projects" }, { "name": "Directories" }, { "name": "Assets" }, { "name": "Attachments" }, { "name": "Filesystem Items" }, { "name": "Collections" }, { "name": "Comments" }, { "name": "Search" }, { "name": "Transcription" }, { "name": "Metadata" }, { "name": "Shares" }, { "name": "Share Templates" }, { "name": "Watermarks" } ] }