{ "swagger": "2.0", "info": { "description": "Public Toggl Focus API.\nNote:\nAuthentication is implemented using a secure cookie stored in __Secure-accounts-session", "title": "Toggl Focus API", "termsOfService": "https://toggl.com/terms/", "contact": {}, "license": { "name": "Toggl Proprietary License" }, "version": "1" }, "host": "localhost:8080", "basePath": "/api", "paths": { "/accounts/me/metadata": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "accounts" ], "summary": "Retrieve user metadata", "operationId": "user-metadata", "parameters": [ { "type": "integer", "description": "Organization ID used to resolve scoped beta flags", "name": "organization_id", "in": "query" }, { "type": "integer", "description": "Workspace ID used to resolve scoped beta flags", "name": "workspace_id", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/authentication.UserMetadata" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/backoffice/betaflags": { "get": { "security": [ { "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Return all beta flags", "operationId": "beta-features-all", "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/betafeatures.BetaFeature" } } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Allows to create a new beta flag", "operationId": "beta-features-post", "parameters": [ { "description": "Beta flag data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/betafeatures.BetaFeaturePayload" } } ], "responses": { "201": { "description": "Successful operation", "schema": { "$ref": "#/definitions/betafeatures.BetaFeature" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/backoffice/betaflags/code/{code}": { "put": { "security": [ { "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Allows to change value of enabled for all flag", "operationId": "beta-features-update", "parameters": [ { "type": "string", "description": "Code of beta flag", "name": "code", "in": "path", "required": true }, { "description": "Beta flag data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/backoffice.betaFeaturePayload" } } ], "responses": { "204": { "description": "Successful operation", "schema": { "type": "string" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/backoffice/betaflags/{user_id}": { "get": { "security": [ { "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Return all beta flags with vaue for user", "operationId": "beta-features-user", "parameters": [ { "type": "integer", "description": "User ID", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/betafeatures.BetaFeatureUser" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Allows to set value of the beta flag", "operationId": "beta-features-user-put", "parameters": [ { "type": "integer", "description": "User ID", "name": "user_id", "in": "path", "required": true } ], "responses": { "204": { "description": "Successful operation", "schema": { "type": "string" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/backoffice/organizations/{organization_id}/workspaces/{workspace_id}": { "get": { "security": [ { "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Get Focus workspace overview", "operationId": "backoffice-workspace-overview", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/backoffice.WorkspaceOverviewResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Workspace not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/backoffice/organizations/{organization_id}/workspaces/{workspace_id}/import-jobs": { "get": { "security": [ { "cookieAuth": [] } ], "description": "BackOffice-authenticated paginated listing of Track/Plan import jobs for a Focus workspace, newest first.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "List Focus workspace import jobs", "operationId": "backoffice-list-workspace-import-jobs", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "integer", "description": "filter by source product ID (1 = Track, 4 = Plan)", "name": "source_product_id", "in": "query" }, { "type": "string", "description": "filter by status, comma-separated (pending, active, completed, failed)", "name": "status", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.PageWithTotal-backoffice_ImportJobView" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Workspace not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/backoffice/organizations/{organization_id}/workspaces/{workspace_id}/projects": { "get": { "security": [ { "cookieAuth": [] } ], "description": "BackOffice-authenticated paginated listing of projects in a Focus workspace. Bypasses workspace membership checks.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "List Focus workspace projects", "operationId": "backoffice-list-workspace-projects", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "name", "-name", "client_id", "-client_id", "client_name", "-client_name", "parent_project_id", "-parent_project_id", "private", "-private", "active", "-active", "billable", "-billable", "created_at", "-created_at", "updated_at", "-updated_at", "toggl_user_id", "-toggl_user_id", "created_by_user", "pinned", "-pinned", "relevance", "-relevance" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" }, { "type": "boolean", "description": "filter by archived state (true = archived only, false = active only, omit = active only, empty = all projects)", "name": "archived", "in": "query" }, { "type": "string", "description": "filter by project name or client name", "name": "name", "in": "query" }, { "type": "string", "description": "filter by deletion state (omit = active only, 'all'/'2'/empty = all projects, 'true'/'1' = deleted only, 'false'/'0' = active only)", "name": "deleted", "in": "query" }, { "type": "boolean", "description": "includes the projects' rate data", "name": "include_rates", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.PageWithTotal-models_ProjectWithAggregations" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Workspace not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/backoffice/user": { "get": { "security": [ { "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Search user using email", "operationId": "user-search", "parameters": [ { "type": "string", "description": "Search query", "name": "search", "in": "query", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/user.User" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/backoffice/user/{user_id}": { "get": { "security": [ { "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Fetch user using ID", "operationId": "user-get", "parameters": [ { "type": "integer", "description": "User ID", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/user.User" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/backoffice/users/{user_id}/time-entries": { "get": { "security": [ { "cookieAuth": [] } ], "description": "BackOffice-authenticated keyset listing of one user's time entries in one workspace. view=logged lists entries with logged time (ordered by start desc); view=planned lists entries with planned time (ordered by planned_start desc). An entry carrying both appears in both views. Deliberately historical: entries remain listed after the user leaves the workspace. Pagination is cursor-based so a delete between pages cannot make rows drift past the reader: follow next_cursor to walk older and prev_cursor to walk newer, stopping when the one you follow is null. Data is always newest-first. The total lives on the sibling /count endpoint because it depends only on the filters.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "List a Focus user's time entries (logged or planned view)", "operationId": "backoffice-list-user-time-entries", "parameters": [ { "type": "integer", "description": "Account-level user ID", "name": "user_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "query", "required": true }, { "type": "string", "description": "logged or planned", "name": "view", "in": "query", "required": true }, { "type": "string", "description": "inclusive start date (YYYY-MM-DD, UTC)", "name": "start_date", "in": "query" }, { "type": "string", "description": "inclusive end date (YYYY-MM-DD, UTC)", "name": "end_date", "in": "query" }, { "type": "string", "description": "active (default), deleted, or all", "name": "deleted", "in": "query" }, { "type": "string", "description": "substring filter on description", "name": "description", "in": "query" }, { "type": "string", "description": "opaque position from a previous response; omit for the newest-first first page", "name": "cursor", "in": "query" }, { "type": "string", "description": "older (default) or newer; requires a cursor", "name": "direction", "in": "query" }, { "type": "boolean", "description": "start AT the cursor row instead of below it; requires a cursor and direction=older", "name": "inclusive", "in": "query" }, { "type": "integer", "description": "rows per window (default 50, max 100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/backoffice.TimeEntriesPage" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "User not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/backoffice/users/{user_id}/time-entries/count": { "get": { "security": [ { "cookieAuth": [] } ], "description": "Companion to the keyset listing. The total depends only on the filters, never on where in the results the reader is, so it is its own request the client makes once per filter change instead of once per page — and it is available on an anchored deep link, where no \"first page\" is ever fetched.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Count a Focus user's time entries matching the listing filters", "operationId": "backoffice-count-user-time-entries", "parameters": [ { "type": "integer", "description": "Account-level user ID", "name": "user_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "query", "required": true }, { "type": "string", "description": "logged or planned", "name": "view", "in": "query", "required": true }, { "type": "string", "description": "inclusive start date (YYYY-MM-DD, UTC)", "name": "start_date", "in": "query" }, { "type": "string", "description": "inclusive end date (YYYY-MM-DD, UTC)", "name": "end_date", "in": "query" }, { "type": "string", "description": "active (default), deleted, or all", "name": "deleted", "in": "query" }, { "type": "string", "description": "substring filter on description", "name": "description", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/backoffice.TimeEntriesTotal" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "User not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/backoffice/users/{user_id}/time-entries/restore": { "patch": { "security": [ { "cookieAuth": [] } ], "description": "Bulk form of the single restore, for the listing's selection. All entries must belong to the user in the given workspace and still be deleted. The batch is ALL-OR-NOTHING and capped at 100 ids: one rejected entry (missing, already active, another user's, inside a submitted/approved timesheet period, or referencing a draft project) rolls the whole batch back untouched and returns the same status a single restore would, so the caller can narrow the selection and retry. Each restored entry emits the same sync event a user-initiated restore would, plus its own backoffice audit record carrying the reason.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Restore a batch of a Focus user's soft-deleted time entries", "operationId": "backoffice-bulk-restore-user-time-entries", "parameters": [ { "type": "integer", "description": "Account-level user ID (entry owner)", "name": "user_id", "in": "path", "required": true }, { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "query", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "query", "required": true }, { "description": "Entry ids and mandatory reason", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/backoffice.timeEntryBulkRestorePayload" } } ], "responses": { "204": { "description": "Restored" }, "400": { "description": "Invalid request, or more ids than the batch limit", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "User not found, or an entry is missing / not deleted / not the user's", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "An entry is locked by a timesheet period", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/backoffice/users/{user_id}/time-entries/{time_entry_id}": { "delete": { "security": [ { "cookieAuth": [] } ], "description": "Requires a written reason. Emits the same sync event a user-initiated delete would (product clients and reporting observe it) and cascades timesheet-flag cleanup. Entries inside a submitted/approved timesheet period are refused with 409.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Soft-delete one of a Focus user's time entries", "operationId": "backoffice-delete-user-time-entry", "parameters": [ { "type": "integer", "description": "Account-level user ID (entry owner)", "name": "user_id", "in": "path", "required": true }, { "type": "integer", "description": "Time entry ID", "name": "time_entry_id", "in": "path", "required": true }, { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "query", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "query", "required": true }, { "description": "Mandatory reason", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/backoffice.timeEntryMutationPayload" } } ], "responses": { "204": { "description": "Deleted" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "User or time entry not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Entry is locked by a timesheet period", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/backoffice/users/{user_id}/time-entries/{time_entry_id}/restore": { "patch": { "security": [ { "cookieAuth": [] } ], "description": "Requires a written reason. Emits the same sync event a user-initiated restore would. Restoring into a submitted/approved timesheet period is refused with 409.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Restore one of a Focus user's soft-deleted time entries", "operationId": "backoffice-restore-user-time-entry", "parameters": [ { "type": "integer", "description": "Account-level user ID (entry owner)", "name": "user_id", "in": "path", "required": true }, { "type": "integer", "description": "Time entry ID", "name": "time_entry_id", "in": "path", "required": true }, { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "query", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "query", "required": true }, { "description": "Mandatory reason", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/backoffice.timeEntryMutationPayload" } } ], "responses": { "204": { "description": "Restored" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "User or time entry not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Entry is locked by a timesheet period", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/dev/organizations/{organization_id}/workspaces/{workspace_id}/roles-with-permissions": { "get": { "security": [ { "bearerAuth": [] } ], "description": "Returns workspace-level roles and their permissions for the given organization and workspace. Permissions are filtered by the current user's plan.", "produces": [ "application/json" ], "tags": [ "dev" ], "summary": "Get roles with permissions for a workspace", "operationId": "get-roles-with-permissions", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "List of roles with permissions", "schema": { "type": "array", "items": { "$ref": "#/definitions/types.Role" } } }, "400": { "description": "Invalid request (e.g. invalid IDs)", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "No access to organization", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Organization not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/importer/{organization_id}/sources": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of workspaces, entities that can be used to import to Focus.", "produces": [ "application/json" ], "tags": [ "importer" ], "summary": "List workspaces, entities available to use as import source.", "operationId": "list-sources", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/importer.source" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/importer/{organization_id}/{workspace_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the current import job for a workspace", "produces": [ "application/json" ], "tags": [ "importer" ], "summary": "Get current import job for a workspace", "operationId": "get-current-import-job", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/importer.ImportJob" } }, "204": { "description": "No Content", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Starts the import process from the specified workspace and entity from specified product.", "produces": [ "application/json" ], "tags": [ "importer" ], "summary": "Start import from chosen product, workspace and entitity.", "operationId": "start-import", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Import payload", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/importer.importRequest" } } ], "responses": { "200": { "description": "The created import job", "schema": { "$ref": "#/definitions/importer.ImportJob" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Not authorized to import into this workspace", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Already have an import in progress", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/importer/{organization_id}/{workspace_id}/jobs": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of import jobs for a workspace with optional filters", "produces": [ "application/json" ], "tags": [ "importer" ], "summary": "List import jobs for a workspace", "operationId": "list-import-jobs", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Filter by source product ID (1 for Track, 4 for Plan)", "name": "source_product_id", "in": "query" }, { "type": "string", "description": "Filter by status, comma-separated (pending, active, completed, failed)", "name": "status", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/importer.ImportJobResponse" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/importer/{organization_id}/{workspace_id}/jobs/{job_id}/log": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Downloads the import entity/linking log for a workspace job as CSV.", "produces": [ "text/csv" ], "tags": [ "importer" ], "summary": "Download import log for a workspace job", "operationId": "download-import-log", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "import job ID", "name": "job_id", "in": "path", "required": true } ], "responses": { "200": { "description": "CSV import log", "schema": { "type": "string" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Import job or log not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/importer/{organization_id}/{workspace_id}/preview": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Preview for importing data", "produces": [ "application/json" ], "tags": [ "importer" ], "summary": "Preview for import", "operationId": "preview-import", "parameters": [ { "type": "integer", "description": "target organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "target workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Import payload", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/importer.importRequest" } } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/importer.importPreview" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Not authorized to preview a full-workspace import", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/importer/{organization_id}/{workspace_id}/preview/{entity_type}": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a paginated page of entity rows that match the import preview rules. The response intentionally does not include a total count; request the next page until fewer than per_page rows are returned.", "produces": [ "application/json" ], "tags": [ "importer" ], "summary": "Preview import entity rows", "operationId": "preview-import-details", "parameters": [ { "type": "integer", "description": "target organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "target workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "enum": [ "members", "clients", "projects", "tasks", "time_entries" ], "type": "string", "description": "entity type", "name": "entity_type", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "description": "Import payload", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/importer.importRequest" } } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/importer.importPreviewDetailPage" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Not authorized to preview a full-workspace import", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/importer/{organization_id}/{workspace_id}/{job_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the import job for a workspace", "produces": [ "application/json" ], "tags": [ "importer" ], "summary": "Get import job for a workspace", "operationId": "get-import-job", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "import job ID", "name": "job_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/importer.ImportJob" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not found", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/audit-log/{from}/{to}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns audit log events across every workspace of the organization within the\ngiven time range, with the same summaries as the workspace endpoint.\nPass workspace_id to narrow the result to a single workspace.\nWorkspace summaries cover only the workspaces the caller can read, so an\norganization admin who is not a member of every workspace sees events whose\nworkspace name is absent.\nRequires view_audit_log on the organization, or view_workspace_audit_log on the\nworkspace given by workspace_id — which must belong to that organization; a\nworkspace from another organization is refused even with a grant on it.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "audit_log" ], "summary": "Fetch audit log events for a whole organization.", "operationId": "get-organization-audit-log", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "string", "description": "Start datetime (RFC3339)", "name": "from", "in": "path", "required": true }, { "type": "string", "description": "End datetime (RFC3339)", "name": "to", "in": "path", "required": true }, { "type": "integer", "description": "Restrict the result to a single workspace", "name": "workspace_id", "in": "query" }, { "type": "string", "description": "Entity type(s), comma-separated; workspace_logs expands to every type except time_entry", "name": "entity_type", "in": "query" }, { "type": "integer", "description": "Entity ID", "name": "entity_id", "in": "query" }, { "type": "string", "description": "Action(s), comma-separated", "name": "action", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "User ID(s)", "name": "user_id", "in": "query" }, { "type": "integer", "description": "Page size, capped at 1000", "name": "page_size", "in": "query" }, { "type": "integer", "description": "Page number, capped at 10000", "name": "page_number", "in": "query" }, { "type": "boolean", "description": "Return all events without pagination; requires workspace_id", "name": "export", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/auditlog.Response" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User does not have access to the organization audit log", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Server error", "schema": { "$ref": "#/definitions/response.Error" } }, "503": { "description": "Authorization service unavailable", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/extension-integrations": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns all custom browser extension integrations for the organization.", "produces": [ "application/json" ], "tags": [ "extension integrations" ], "summary": "List extension integrations", "operationId": "list-extension-integrations", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.ExtensionIntegration" } } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new custom browser extension integration definition. The client supplies the UUID `id` so creates are idempotent across retries.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "extension integrations" ], "summary": "Create a new extension integration", "operationId": "create-extension-integration", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "description": "Extension integration payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/extensionintegration.CreatePayload" } } ], "responses": { "201": { "description": "Extension integration created successfully", "schema": { "$ref": "#/definitions/models.ExtensionIntegration" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Conflict — id already exists", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/extension-integrations/{extension_integration_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a custom browser extension integration by ID.", "produces": [ "application/json" ], "tags": [ "extension integrations" ], "summary": "Get extension integration by ID", "operationId": "get-extension-integration", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "string", "description": "Extension integration ID (UUID)", "name": "extension_integration_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.ExtensionIntegration" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates or updates a custom browser extension integration. The UUID in the URL is canonical: same UUID + same body is idempotent. Allows the extension to sync offline-authored drafts and edits with one call.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "extension integrations" ], "summary": "Upsert extension integration", "operationId": "upsert-extension-integration", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "string", "description": "Extension integration ID (UUID)", "name": "extension_integration_id", "in": "path", "required": true }, { "description": "Extension integration payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/extensionintegration.UpsertPayload" } } ], "responses": { "200": { "description": "Successfully upserted", "schema": { "$ref": "#/definitions/models.ExtensionIntegration" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Conflict — id belongs to a different organization", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Soft-deletes a custom browser extension integration.", "produces": [ "application/json" ], "tags": [ "extension integrations" ], "summary": "Delete an extension integration", "operationId": "delete-extension-integration", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "string", "description": "Extension integration ID (UUID)", "name": "extension_integration_id", "in": "path", "required": true } ], "responses": { "204": { "description": "Successfully deleted" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/groups": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a group under an organization for the given users and workspaces.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "organization" ], "summary": "Create organization group", "operationId": "create-organization-group", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "description": "group data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/organization.GroupRequest" } } ], "responses": { "201": { "description": "Successful operation", "schema": { "$ref": "#/definitions/orgprivate.Group" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User does not have access", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/groups/me": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Get groups the current user belongs to", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "organization" ], "summary": "Get current user's groups", "operationId": "get-my-groups", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/client.UserGroupInfoResponse" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User does not have access to the organization", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/groups/{group_id}": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Updates a group under an organization.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "organization" ], "summary": "Update organization group", "operationId": "update-organization-group", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "group ID", "name": "group_id", "in": "path", "required": true }, { "description": "group data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/organization.GroupRequest" } } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/orgprivate.Group" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User does not have access", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Group not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes a group from an organization.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "organization" ], "summary": "Delete organization group", "operationId": "delete-organization-group", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "group ID", "name": "group_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID (required for permission check)", "name": "workspace_id", "in": "query", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "object", "additionalProperties": { "type": "boolean" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User does not have access", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Group not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/groups/{group_id}/user_role": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Updates the Focus role of a group member. Other products' roles are not affected. A null focus_role_id clears the role. The workspace_id is used for the permission check.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "organization" ], "summary": "Update a member's Focus role in a group", "operationId": "update-organization-group-user-role", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "group ID", "name": "group_id", "in": "path", "required": true }, { "description": "role data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/organization.GroupUserRoleRequest" } } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "object", "additionalProperties": { "type": "boolean" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User does not have access", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Group member not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/member-tags": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the organization's assigned member tags. Requires the workspace-scoped manage_team_reports permission (workspace_id).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "organization" ], "summary": "Get organization member tags", "operationId": "get-organization-member-tags", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID (required for permission check)", "name": "workspace_id", "in": "query", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/organization.MemberTag" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User does not have permission to view member tags", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/public-holidays": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns public holidays of organization users", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "public-holidays" ], "summary": "Get public holidays of organization users", "operationId": "get-public-holidays-by-user-ids", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "User IDs", "name": "user_id", "in": "query", "required": true }, { "type": "string", "description": "Start date (YYYY-MM-DD)", "name": "start_date", "in": "query", "required": true }, { "type": "string", "description": "End date (YYYY-MM-DD)", "name": "end_date", "in": "query", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/shareddata.PublicHolidayWithUserAccountID" } } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/roles": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Get organization roles", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "organization" ], "summary": "Get organization roles", "operationId": "get-organization-roles", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/types.Role" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User does not have access to the organization", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/subscriptions/current": { "get": { "description": "Get current subscription.", "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Get current subscription", "operationId": "get-current-subscription", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/subscription.getCurrentResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/subscriptions/features-upsell": { "get": { "description": "Get the organization's features and the lowest-priced plan that unlocks each. Drives in-app upsells for paid features; upsell_plan_id is null for features the organization's current plan already includes.", "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Get feature upsells", "operationId": "get-features-upsell", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/subscription.getFeaturesUpsellResponse" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/subscriptions/plans": { "get": { "description": "Get the Focus plans from the plan catalog, including each plan's seat cap (max_user_count) when one is configured.", "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Get Focus plans", "operationId": "get-subscription-plans", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/subscription.getPlansResponse" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/subscriptions/trials/current": { "get": { "description": "Get the current active trial for the Focus product.", "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Get current trial", "operationId": "get-current-trial", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Current active trial", "schema": { "$ref": "#/definitions/subscription.getCurrentTrialResponse" } }, "204": { "description": "No active trial found" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Subscription not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/teams": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Gets groups for a workspace, checking view_user_groups permission.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "organization" ], "summary": "Get organization teams.", "operationId": "get-organization-teams", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID (required for permission check)", "name": "workspace_id", "in": "query", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "Direction to sort by (asc/desc)", "name": "sort_dir", "in": "query" }, { "type": "string", "description": "Filter by name", "name": "filter", "in": "query" }, { "type": "string", "description": "Filter by team name and its members' names", "name": "query", "in": "query" }, { "type": "integer", "description": "Filter groups that contain this organization user", "name": "organization_user_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Filter by group IDs", "name": "group_ids", "in": "query" }, { "type": "boolean", "description": "Filter by active members only", "name": "active_members_only", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/page.Envelope-orgprivate_Group" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User does not have permission to view groups", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/timeoff": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the time off of the given organization users with personal detail stripped: each entry carries only its id, the user it belongs to, and the start and end of the period — no category and no audit timestamps. Available to any member of the organization. `user_id` is required and repeatable, and so is the `start_date`/`end_date` window; both are dates (YYYY-MM-DD), interpreted in UTC, and `end_date` is inclusive of that whole day. An entry is returned when its period overlaps the window at either edge, so an entry that starts before `start_date` or ends after `end_date` is still included.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Get time offs of organization users", "operationId": "get-timeoffs-by-user-ids", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "User IDs", "name": "user_id", "in": "query", "required": true }, { "type": "string", "description": "From date (YYYY-MM-DD)", "name": "start_date", "in": "query", "required": true }, { "type": "string", "description": "To date (YYYY-MM-DD)", "name": "end_date", "in": "query", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/shareddata.TimeOffWithoutPersonalInfo" } } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/timeoff/users/{user_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the full time off entries of one organization user, including the category and the creation and last-modification timestamps. Requires the `manage_time_off` organization permission — this applies to reading as well, and to a caller's own entries. The `from`/`to` window is required; both are dates (YYYY-MM-DD), interpreted in UTC, and `to` is inclusive of that whole day. An entry is returned when its period overlaps the window at either edge, so an entry that starts before `from` or ends after `to` is still included.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Get time off for organization user", "operationId": "get-timeoff-for-user", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "User ID", "name": "user_id", "in": "path", "required": true }, { "type": "string", "description": "From date (YYYY-MM-DD)", "name": "from", "in": "query", "required": true }, { "type": "string", "description": "To date (YYYY-MM-DD)", "name": "to", "in": "query", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/timeoff.TimeOff" } } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Updates one or more existing time off entries of the specified user in a single call. The request body is an array: each element identifies the entry by its `timeoff_id` and carries the new `start_time` and `end_time` (RFC3339) plus an optional `type`. Every element replaces the entry in full, so omitting `type` clears the entry's existing category rather than leaving it unchanged — resend the current value to keep it. Include each `timeoff_id` at most once: with duplicates, which element wins is undefined. Elements whose `timeoff_id` does not match an entry of the user are skipped. All elements are applied in a single transaction: if applying them would leave any two of the user's approved or pending time off entries overlapping (entries created through this API are approved), the whole request fails with a 409 and nothing is updated. Requires the `manage_time_off` organization permission. Responds 200 with the entries that were actually updated.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Update time off for the specified user", "operationId": "update-timeoff-for-user", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "User ID", "name": "user_id", "in": "path", "required": true }, { "description": "Time off payload", "name": "timeoff", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/timeoff.TimeOffBatchUpdateInput" } } } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/timeoff.TimeOff" } } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Overlapping time off entry", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates one or more time off entries for the specified user in a single call. The request body is an array: each element needs a `start_time` and an `end_time` (RFC3339) and may carry an optional `type`. All elements are created in a single transaction: a period that overlaps one of the user's approved or pending time off entries — or another element of the same request — fails the whole request with a 409 and nothing is created (entries created through this API are approved). Requires the `manage_time_off` organization permission. Responds 200 with the created entries, each including the id it was assigned.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Create time off for the specified user", "operationId": "create-timeoff-for-user", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "User ID", "name": "user_id", "in": "path", "required": true }, { "description": "Time off payload", "name": "timeoff", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/timeoff.TimeOffBatchCreateInput" } } } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/timeoff.TimeOff" } } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Overlapping time off entry", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes one or more time off entries of the specified user. The request body is an array of time off ids. Ids that do not match an entry of the user are skipped silently — the response does not indicate how many entries were deleted. Requires the `manage_time_off` organization permission. Responds 204 with no body.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Delete time off for the specified user", "operationId": "delete-timeoff-for-user", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "User ID", "name": "user_id", "in": "path", "required": true }, { "description": "Time off ids payload", "name": "ids", "in": "body", "required": true, "schema": { "type": "array", "items": { "type": "integer" } } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/users": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Proxies to accounts organization users endpoint with guest scoping. Guests only see users who share projects with them.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "organization" ], "summary": "Get organization users", "operationId": "get-organization-users", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Filter by workspace IDs", "name": "workspaces", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Filter by user account IDs", "name": "user_account_ids", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Filter by organization user IDs", "name": "org_user_ids", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Filter by group IDs", "name": "groups", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "Filter by toggl products", "name": "toggl_products", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "Filter by active status", "name": "active_status", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Filter by roles", "name": "roles", "in": "query" }, { "type": "boolean", "description": "Only return admins", "name": "only_admins", "in": "query" }, { "type": "string", "description": "Filter by name or email", "name": "filter", "in": "query" }, { "type": "string", "description": "Sort direction (asc/desc)", "name": "sort_dir", "in": "query" }, { "type": "integer", "description": "Page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Filter by tag IDs", "name": "tag_ids", "in": "query" }, { "type": "boolean", "description": "Include working hours in response", "name": "include_working_hours", "in": "query" }, { "type": "boolean", "description": "Include user rates data for each user", "name": "include_rates", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Pin specific users at the top (respects array order)", "name": "pinned_ids", "in": "query" }, { "type": "boolean", "description": "Filters users that do or do not belong to a team", "name": "has_group", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "Filter members by user custom-field values, fieldID:value entries ANDed together; requires workspaces to name exactly one workspace", "name": "cf_filter", "in": "query" }, { "type": "boolean", "description": "Include each member's user custom-field values; requires workspaces to name exactly one workspace", "name": "include_custom_fields", "in": "query" } ], "responses": { "200": { "description": "Successful operation; custom_field_values is present only when include_custom_fields=true and the caller holds view_workspace_user_custom_fields with the beta enabled", "schema": { "type": "array", "items": { "$ref": "#/definitions/organization.OrganizationUserResponse" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User does not have access to the organization", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "cf_filter matches too many members; narrow the filter", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workinghours/users/{user_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns working hours for organization user", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Working Hours" ], "summary": "Get working hours for organization user", "operationId": "get-working-hours-for-user", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "User ID", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/shareddata.WorkingHours" } } }, "400": { "description": "Invalid year", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Updates working hours for the specified user", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Working Hours" ], "summary": "Update working hours for the specified user", "operationId": "update-working-hours-for-user", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "User ID", "name": "user_id", "in": "path", "required": true }, { "description": "Working hours payload", "name": "working_hours", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/shareddata.WorkingHoursUpdateInput" } } } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/shareddata.WorkingHours" } } }, "400": { "description": "Invalid year", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates working hours for the specified user", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Working Hours" ], "summary": "Create working hours for the specified user", "operationId": "create-working-hours-for-user", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "User ID", "name": "user_id", "in": "path", "required": true }, { "description": "Working hours payload", "name": "working_hours", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/shareddata.WorkingHoursCreateInput" } } } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/shareddata.WorkingHours" } } }, "400": { "description": "Invalid year", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes working hours for the specified user", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Working Hours" ], "summary": "Delete working hours for the specified user", "operationId": "delete-working-hours-for-user", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "User ID", "name": "user_id", "in": "path", "required": true }, { "description": "Working hour ids payload", "name": "ids", "in": "body", "required": true, "schema": { "type": "array", "items": { "type": "integer" } } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid year", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/alerts": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns alert configurations. With no filter, returns all rules in the workspace.\n`rule_type` and `project_id` may be repeated to filter by multiple values.\nInside `project_id`, a `null` value also includes workspace defaults; workspace defaults that effectively apply to a filtered project (no project-level override of the same `rule_type`) are surfaced too.\n`scope=workspace` returns only workspace-level rules and is mutually exclusive with `project_id`.", "produces": [ "application/json" ], "tags": [ "alerts" ], "summary": "List alert configurations", "operationId": "list-alerts", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "enum": [ "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string" }, "collectionFormat": "csv", "description": "order by (repeatable; prefix with `-` for descending)", "name": "order_by", "in": "query" }, { "type": "array", "items": { "enum": [ "time_estimate", "fixed_fee", "time_tracking_reminder" ], "type": "string" }, "collectionFormat": "csv", "description": "filter by rule type (repeatable)", "name": "rule_type", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by project (repeatable); a null value also includes workspace defaults", "name": "project_id", "in": "query" }, { "type": "string", "description": "filter by scope (only `workspace` is supported, returns workspace-level rules)", "name": "scope", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/alert.Rule" } } }, "400": { "description": "Invalid query parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new alert or reminder configuration.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "alerts" ], "summary": "Create an alert configuration", "operationId": "create-alert", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Alert configuration payload", "name": "alert", "in": "body", "required": true, "schema": { "$ref": "#/definitions/alert.CreatePayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/alert.Rule" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/alerts/{alert_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a single alert or reminder configuration by ID.", "produces": [ "application/json" ], "tags": [ "alerts" ], "summary": "Get an alert configuration", "operationId": "get-alert", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "alert configuration ID", "name": "alert_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/alert.Rule" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Alert not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Soft-deletes an alert or reminder configuration.", "tags": [ "alerts" ], "summary": "Delete an alert configuration", "operationId": "delete-alert", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "alert configuration ID", "name": "alert_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Alert not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Updates only the provided fields. Omitted fields keep their existing values.\n`config` is replaced wholesale when present (no field-level merge inside the JSON object).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "alerts" ], "summary": "Partially update an alert configuration", "operationId": "partial-update-alert", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "alert configuration ID", "name": "alert_id", "in": "path", "required": true }, { "description": "Fields to update", "name": "alert", "in": "body", "required": true, "schema": { "$ref": "#/definitions/alert.PartialUpdatePayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/alert.Rule" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Alert not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/attachments/storage": { "get": { "description": "Workspace attachment storage usage and limit; enforced only for free organizations.", "produces": [ "application/json" ], "tags": [ "attachments" ], "summary": "Get workspace attachment storage usage", "operationId": "get-workspace-attachment-storage", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/attachmentstorage.Usage" } }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/audit-log/{from}/{to}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns audit log events for the workspace within the given time range,\nenriched with user, project, client, task, workspace, custom field,\ncustom field option and group summaries.\nThe caller must have the view_workspace_audit_log permission on the workspace.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "audit_log" ], "summary": "Fetch audit log events.", "operationId": "get-audit-log", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "Start datetime (RFC3339)", "name": "from", "in": "path", "required": true }, { "type": "string", "description": "End datetime (RFC3339)", "name": "to", "in": "path", "required": true }, { "type": "string", "description": "Entity type(s), comma-separated; workspace_logs expands to every type except time_entry", "name": "entity_type", "in": "query" }, { "type": "integer", "description": "Entity ID", "name": "entity_id", "in": "query" }, { "type": "string", "description": "Action(s), comma-separated", "name": "action", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "User ID(s)", "name": "user_id", "in": "query" }, { "type": "integer", "description": "Page size, capped at 1000", "name": "page_size", "in": "query" }, { "type": "integer", "description": "Page number, capped at 10000", "name": "page_number", "in": "query" }, { "type": "boolean", "description": "Return all events without pagination", "name": "export", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/auditlog.Response" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User does not have access to the workspace audit log", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Server error", "schema": { "$ref": "#/definitions/response.Error" } }, "503": { "description": "Authorization service unavailable", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/billable-rates/projects/rates": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the project billable rate effective at the given date for each requested project. Projects with no rate (or that the actor cannot access) are absent from the response.", "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "Get current project billable rates at a date", "operationId": "get-projects-billable-rates", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "project IDs", "name": "project_id", "in": "query", "required": true }, { "type": "string", "format": "date", "description": "as-of date (YYYY-MM-DD)", "name": "date", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/rate.RateWithEntityAPI" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/billable-rates/projects/users/rates": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "List all project-user billable rates filtered by project, user, or date (at least one filter is required)", "operationId": "get-all-project-user-billable-rates", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by project IDs (max 200)", "name": "project_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by user IDs (max 200)", "name": "user_id", "in": "query" }, { "type": "string", "format": "date", "description": "filter to rates effective on this date", "name": "date", "in": "query" }, { "type": "array", "items": { "enum": [ "start_date", "-start_date", "end_date", "-end_date", "hourly_rate", "-hourly_rate", "currency", "-currency", "entity_id", "-entity_id" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/rate.RateWithEntityAPI" } } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/billable-rates/projects/{project_id}/rates": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "List project billable rates", "operationId": "get-project-billable-rates", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "array", "items": { "enum": [ "start_date", "-start_date", "end_date", "-end_date", "hourly_rate", "-hourly_rate", "currency", "-currency" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/rate.RateAPI" } } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "Create or update a project billable rate", "operationId": "upsert-project-billable-rate", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "description": "Rate payload (hourly_rate in smallest currency unit)", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rate.NewRatePayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/rate.RateAPI" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "Delete project billable rates in a date range", "operationId": "delete-project-billable-rate-range", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "string", "format": "date", "description": "start date (YYYY-MM-DD)", "name": "from", "in": "query", "required": true }, { "type": "string", "format": "date", "description": "end date (YYYY-MM-DD)", "name": "to", "in": "query" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/billable-rates/projects/{project_id}/rates/check": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "Check conflicts for a project billable rate", "operationId": "check-project-billable-rate-conflicts", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "description": "Proposed rate", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rate.NewRatePayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/rate.ConflictCheckResult" } }, "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/billable-rates/projects/{project_id}/users/{user_id}/rates": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "List project-user billable rates", "operationId": "get-project-user-billable-rates", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "integer", "description": "target user ID", "name": "user_id", "in": "path", "required": true }, { "type": "array", "items": { "enum": [ "start_date", "-start_date", "end_date", "-end_date", "hourly_rate", "-hourly_rate", "currency", "-currency" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/rate.RateAPI" } } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "Create or update a project-user billable rate", "operationId": "upsert-project-user-billable-rate", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "integer", "description": "target user ID", "name": "user_id", "in": "path", "required": true }, { "description": "Rate payload (hourly_rate in smallest currency unit)", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rate.NewRatePayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/rate.RateAPI" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "Delete project-user billable rates in a date range", "operationId": "delete-project-user-billable-rate-range", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "integer", "description": "target user ID", "name": "user_id", "in": "path", "required": true }, { "type": "string", "format": "date", "description": "start date (YYYY-MM-DD)", "name": "from", "in": "query", "required": true }, { "type": "string", "format": "date", "description": "end date (YYYY-MM-DD)", "name": "to", "in": "query" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/billable-rates/projects/{project_id}/users/{user_id}/rates/check": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "Check conflicts for a project-user billable rate", "operationId": "check-project-user-billable-rate-conflicts", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "integer", "description": "target user ID", "name": "user_id", "in": "path", "required": true }, { "description": "Proposed rate", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rate.NewRatePayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/rate.ConflictCheckResult" } }, "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/billable-rates/rates/{rate_id}": { "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "Delete a single billable rate by ID", "operationId": "delete-billable-rate-by-id", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "rate ID", "name": "rate_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/billable-rates/users/rates": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "List all workspace-user billable rates", "operationId": "get-all-workspace-user-billable-rates", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by user IDs", "name": "user_id", "in": "query" }, { "type": "array", "items": { "enum": [ "start_date", "-start_date", "end_date", "-end_date", "hourly_rate", "-hourly_rate", "currency", "-currency", "entity_id", "-entity_id" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/rate.RateWithEntityAPI" } } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/billable-rates/users/{user_id}/rates": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "List user billable rates in a workspace", "operationId": "get-workspace-user-billable-rates", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "target user ID", "name": "user_id", "in": "path", "required": true }, { "type": "array", "items": { "enum": [ "start_date", "-start_date", "end_date", "-end_date", "hourly_rate", "-hourly_rate", "currency", "-currency" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/rate.RateAPI" } } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "Create or update a user billable rate in a workspace", "operationId": "upsert-workspace-user-billable-rate", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "target user ID", "name": "user_id", "in": "path", "required": true }, { "description": "Rate payload (hourly_rate in smallest currency unit)", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rate.NewRatePayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/rate.RateAPI" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "Delete user billable rates in a workspace date range", "operationId": "delete-workspace-user-billable-rate-range", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "target user ID", "name": "user_id", "in": "path", "required": true }, { "type": "string", "format": "date", "description": "start date (YYYY-MM-DD)", "name": "from", "in": "query", "required": true }, { "type": "string", "format": "date", "description": "end date (YYYY-MM-DD)", "name": "to", "in": "query" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/billable-rates/users/{user_id}/rates/check": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "Check conflicts for a user billable rate in a workspace", "operationId": "check-workspace-user-billable-rate-conflicts", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "target user ID", "name": "user_id", "in": "path", "required": true }, { "description": "Proposed rate", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rate.NewRatePayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/rate.ConflictCheckResult" } }, "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/billable-rates/workspace/rates": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the timeline of billable rates for the workspace.", "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "List workspace billable rates", "operationId": "get-workspace-billable-rates", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "enum": [ "start_date", "-start_date", "end_date", "-end_date", "hourly_rate", "-hourly_rate", "currency", "-currency" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/rate.RateAPI" } } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Upserts a billable rate for the workspace.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "Create or update a workspace billable rate", "operationId": "upsert-workspace-billable-rate", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Rate payload (hourly_rate in smallest currency unit)", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rate.NewRatePayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/rate.RateAPI" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes workspace billable rates within the given date range.", "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "Delete workspace billable rates in a date range", "operationId": "delete-workspace-billable-rate-range", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "format": "date", "description": "start date (YYYY-MM-DD)", "name": "from", "in": "query", "required": true }, { "type": "string", "format": "date", "description": "end date (YYYY-MM-DD)", "name": "to", "in": "query" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/billable-rates/workspace/rates/check": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Dry-run: returns what existing rates would be modified or deleted by the proposed rate, without persisting.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "billable-rates" ], "summary": "Check conflicts for a workspace billable rate", "operationId": "check-workspace-billable-rate-conflicts", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Proposed rate", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rate.NewRatePayload" } } ], "responses": { "200": { "description": "Conflicts detected", "schema": { "$ref": "#/definitions/rate.ConflictCheckResult" } }, "204": { "description": "No conflicts" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/capacities/{group}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns working minutes plus gross and remaining scheduled estimates for each requested user or resource.\n'estimated_minutes' is gross timeline work from non-draft task estimates, projected recurring tasks, and planned calendar events.\nWhen 'include_drafts' is true, 'estimated_minutes' also includes task estimates from draft projects.\n'estimated_remaining_minutes' nets each assignee's tracked time and places unfinished work from workspace-local today.\nPlacement uses future working days. Weekends and public holidays are excluded.\nPast and overdue task slices are zero; planned events count only from today.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "capacities" ], "summary": "Get capacity computations", "operationId": "capacity-get-computations", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "enum": [ "users" ], "type": "string", "description": "group of computations", "name": "group", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "get capacity computations for the user given their ID", "name": "user_id", "in": "query", "required": true }, { "type": "string", "description": "start date of computation", "name": "start_date", "in": "query", "required": true }, { "type": "string", "description": "end date of computation", "name": "end_date", "in": "query", "required": true }, { "type": "boolean", "description": "task privacy used to compute for capacity", "name": "private", "in": "query" }, { "type": "array", "items": { "enum": [ "focus", "google_calendar", "outlook_calendar" ], "type": "string" }, "collectionFormat": "csv", "description": "filter task sources", "name": "task_source", "in": "query" }, { "enum": [ "day", "week", "month", "quarter" ], "type": "string", "description": "unit of time for computation. default: day", "name": "unit", "in": "query" }, { "type": "boolean", "description": "include draft-project tasks; requires view_draft_projects permission", "name": "include_drafts", "in": "query" } ], "responses": { "200": { "description": "Computations grouped", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.ComputationGroup" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/composite/projects": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates the main project, project members, and milestones. Milestones are automatically associated with the project.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "composite" ], "summary": "Creates the main project, project members, and milestones.", "operationId": "composite-create-project", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Project composite creation payload", "name": "composite", "in": "body", "required": true, "schema": { "$ref": "#/definitions/composite.CreateProjectPayload" } } ], "responses": { "201": { "description": "Composite project creation success", "schema": { "$ref": "#/definitions/composite.CreateProjectResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/composite/tasks": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates the main task, subtasks, time blocks and time entries in bulk.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "composite" ], "summary": "Creates the main task, subtasks, time blocks and time entries in bulk", "operationId": "composite-create-task", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Tasks composite creation payload", "name": "composite", "in": "body", "required": true, "schema": { "$ref": "#/definitions/composite.CreateTasksPayload" } } ], "responses": { "201": { "description": "Composite task creation success", "schema": { "$ref": "#/definitions/composite.CreateTasksResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Task not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Allocation already exists for the entity", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Allocation unit mismatched, or entity not assigned", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/custom-fields": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of custom fields for the workspace.", "produces": [ "application/json" ], "tags": [ "custom-fields" ], "summary": "List custom fields", "operationId": "list-custom-fields", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "enum": [ "project", "task", "user" ], "type": "string", "description": "filter by entity type", "name": "entity_type", "in": "query" }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "position", "-position", "name", "-name", "created_at", "-created_at" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.PageWithTotal-models_CustomFieldWithOptions" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Feature not available on current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new custom field with the provided details.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "custom-fields" ], "summary": "Create a new custom field", "operationId": "create-custom-field", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Custom field payload", "name": "custom_field", "in": "body", "required": true, "schema": { "$ref": "#/definitions/customfield.CreatePayload" } } ], "responses": { "201": { "description": "Custom field created successfully", "schema": { "$ref": "#/definitions/models.CustomFieldWithOptions" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Feature not available on current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Duplicate field name", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Maximum number of custom fields reached", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/custom-fields/order": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Bulk-updates custom field ordering by persisting position from each id's index in ordered_ids, scoped to the given entity_type. ordered_ids must list exactly the active custom fields for that entity_type.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "custom-fields" ], "summary": "Reorder custom fields", "operationId": "update-custom-fields-order", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Reorder payload", "name": "reorder", "in": "body", "required": true, "schema": { "$ref": "#/definitions/customfield.ReorderPayload" } } ], "responses": { "204": { "description": "Successfully reordered custom fields" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Feature not available on current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/custom-fields/{custom_field_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a custom field with the provided ID.", "produces": [ "application/json" ], "tags": [ "custom-fields" ], "summary": "Get custom field by ID", "operationId": "get-custom-field", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "custom field ID", "name": "custom_field_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.CustomFieldWithOptions" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Feature not available on current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Custom field not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Update an existing custom field.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "custom-fields" ], "summary": "Update custom field", "operationId": "update-custom-field", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "custom field ID", "name": "custom_field_id", "in": "path", "required": true }, { "description": "Custom field payload", "name": "custom_field", "in": "body", "required": true, "schema": { "$ref": "#/definitions/customfield.UpdatePayload" } } ], "responses": { "200": { "description": "Successfully updated custom field", "schema": { "$ref": "#/definitions/models.CustomFieldWithOptions" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Feature not available on current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Custom field not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Duplicate field name", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Soft-deletes a custom field with the provided ID.", "produces": [ "application/json" ], "tags": [ "custom-fields" ], "summary": "Delete a custom field by ID", "operationId": "delete-custom-field", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "custom field ID", "name": "custom_field_id", "in": "path", "required": true } ], "responses": { "204": { "description": "Successfully deleted custom field" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Feature not available on current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Custom field not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/custom-fields/{custom_field_id}/options": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a paginated list of options for the specified custom field, with optional name search.", "produces": [ "application/json" ], "tags": [ "custom-fields" ], "summary": "List options for a custom field", "operationId": "list-custom-field-options", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "custom field ID", "name": "custom_field_id", "in": "path", "required": true }, { "type": "string", "description": "filter by option name", "name": "name", "in": "query" }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "position", "-position", "name", "-name", "created_at", "-created_at" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.PageWithTotal-models_CustomFieldOption" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Feature not available on current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Custom field not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new option for a select or multi_select custom field.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "custom-fields" ], "summary": "Create a new option for a custom field", "operationId": "create-custom-field-option", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "custom field ID", "name": "custom_field_id", "in": "path", "required": true }, { "description": "Option payload", "name": "option", "in": "body", "required": true, "schema": { "$ref": "#/definitions/customfield.CreateOptionPayload" } } ], "responses": { "201": { "description": "Option created successfully", "schema": { "$ref": "#/definitions/models.CustomFieldOption" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Feature not available on current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Custom field not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Duplicate option name", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Maximum number of options reached", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/custom-fields/{custom_field_id}/options/order": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Bulk-updates option ordering for a select/multi_select field by persisting position from each id's index in ordered_ids. Unknown or already-deleted ids are ignored, and any active option omitted from ordered_ids keeps its current relative order at the end.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "custom-fields" ], "summary": "Reorder custom field options", "operationId": "update-custom-field-options-order", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "custom field ID", "name": "custom_field_id", "in": "path", "required": true }, { "description": "Reorder payload", "name": "reorder", "in": "body", "required": true, "schema": { "$ref": "#/definitions/customfield.ReorderOptionsPayload" } } ], "responses": { "204": { "description": "Successfully reordered options" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Feature not available on current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Custom field not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/custom-fields/{custom_field_id}/options/{option_id}": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Update an existing custom field option.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "custom-fields" ], "summary": "Update a custom field option", "operationId": "update-custom-field-option", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "custom field ID", "name": "custom_field_id", "in": "path", "required": true }, { "type": "integer", "description": "option ID", "name": "option_id", "in": "path", "required": true }, { "description": "Option payload", "name": "option", "in": "body", "required": true, "schema": { "$ref": "#/definitions/customfield.UpdateOptionPayload" } } ], "responses": { "200": { "description": "Successfully updated option", "schema": { "$ref": "#/definitions/models.CustomFieldOption" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Feature not available on current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Custom field or option not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Duplicate option name", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Soft-deletes a custom field option with the provided ID.", "produces": [ "application/json" ], "tags": [ "custom-fields" ], "summary": "Delete a custom field option by ID", "operationId": "delete-custom-field-option", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "custom field ID", "name": "custom_field_id", "in": "path", "required": true }, { "type": "integer", "description": "option ID", "name": "option_id", "in": "path", "required": true } ], "responses": { "204": { "description": "Successfully deleted option" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Feature not available on current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Custom field or option not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/goals": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new tracking goal for the authenticated user. Returns 400 when the user already has 4 active goals.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "goals" ], "summary": "Create a goal", "operationId": "create-goal", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Goal payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/goal.CreatePayload" } } ], "responses": { "201": { "description": "Goal created", "schema": { "$ref": "#/definitions/models.Goal" } }, "400": { "description": "Invalid request or max goals reached", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Immutable field or invalid payload", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/goals/positions": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Persists a new display order for the authenticated user's goals. goal_ids must be exactly the set of goal ids returned by GET /goals (all non-deleted goals for the caller, active and inactive) — same set, no more, no less, no duplicates — or 422 is returned.", "consumes": [ "application/json" ], "tags": [ "goals" ], "summary": "Reorder goals", "operationId": "reorder-goals", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Ordered goal IDs", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/goal.ReorderPayload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request body", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "goal_ids does not match the caller's non-deleted goal set", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/goals/preview": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns how many seconds the user has already tracked toward the given (uncreated) goal configuration in its current period. No goal is persisted and no warehouse refresh is triggered.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "goals" ], "summary": "Preview tracked time for an uncreated goal", "operationId": "preview-goal-tracked-time", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Goal payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/goal.CreatePayload" } } ], "responses": { "200": { "description": "Tracked-time preview", "schema": { "$ref": "#/definitions/models.GoalPreview" } }, "400": { "description": "Invalid request body", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Invalid payload", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/goals/{goal_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the goal if it belongs to the authenticated user in the workspace. Returns 204 when the goal does not exist or is not owned by the user.", "produces": [ "application/json" ], "tags": [ "goals" ], "summary": "Get a goal", "operationId": "get-goal", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "goal ID", "name": "goal_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.Goal" } }, "204": { "description": "Goal not found or not accessible" }, "400": { "description": "Invalid goal ID", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Soft-deletes a goal. Returns 404 when the goal does not exist or is not owned by the user.", "tags": [ "goals" ], "summary": "Delete a goal", "operationId": "delete-goal", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "goal ID", "name": "goal_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid goal ID", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Goal not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Applies a partial update to an existing goal. Immutable fields (project_ids, task_ids, tag_ids, client_ids, billable, recurrence, monthly_anchor, start_date) cannot be changed.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "goals" ], "summary": "Update a goal", "operationId": "update-goal", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "goal ID", "name": "goal_id", "in": "path", "required": true }, { "description": "Fields to update", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/goal.UpdatePayload" } } ], "responses": { "200": { "description": "Updated goal", "schema": { "$ref": "#/definitions/models.Goal" } }, "400": { "description": "Invalid goal ID or request body", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Goal not found", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Immutable field or invalid payload", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/integrations/calendar": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "List calendar integrations, i.e. the email accounts connected.", "produces": [ "text/plain" ], "tags": [ "calendar" ], "summary": "List calendar integrations", "operationId": "calendar-integrations-list", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "List of integrations, aka connected emails", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.IntegrationWithCalendars" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/integrations/calendar/mappings": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns all mapping rules for the calling user in the workspace, ordered by title.", "produces": [ "application/json" ], "tags": [ "calendar" ], "summary": "List calendar event mapping rules", "operationId": "calendar-mappings-list", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "List of mapping rules", "schema": { "type": "array", "items": { "$ref": "#/definitions/mapping.Rule" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new mapping rule. If a rule with the same normalized title already exists for this user, it is updated in place (upsert semantics). task_id and project_id are both optional, but at least one is required. Supplying both attaches the resulting time entry to the task and uses the project as an explicit override.", "produces": [ "application/json" ], "tags": [ "calendar" ], "summary": "Create or upsert a calendar event mapping rule", "operationId": "calendar-mappings-create", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Mapping rule", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/calendar.mappingRequest" } } ], "responses": { "201": { "description": "Created or upserted mapping rule", "schema": { "$ref": "#/definitions/mapping.Rule" } }, "400": { "description": "Validation error", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Target project or task not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/integrations/calendar/mappings/{mapping_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a single mapping rule by ID.", "produces": [ "application/json" ], "tags": [ "calendar" ], "summary": "Get a calendar event mapping rule", "operationId": "calendar-mappings-get", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "mapping rule ID", "name": "mapping_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Mapping rule", "schema": { "$ref": "#/definitions/mapping.Rule" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Fully replaces the title and target of an existing mapping rule. task_id and project_id are both optional, but at least one is required. Supplying both attaches the resulting time entry to the task and uses the project as an explicit override.", "produces": [ "application/json" ], "tags": [ "calendar" ], "summary": "Update a calendar event mapping rule", "operationId": "calendar-mappings-update", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "mapping rule ID", "name": "mapping_id", "in": "path", "required": true }, { "description": "Mapping rule", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/calendar.mappingRequest" } } ], "responses": { "200": { "description": "Updated mapping rule", "schema": { "$ref": "#/definitions/mapping.Rule" } }, "400": { "description": "Validation error", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Title conflict", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes a mapping rule. Returns 204 on success or 404 if the rule does not exist or belongs to a different user.", "tags": [ "calendar" ], "summary": "Delete a calendar event mapping rule", "operationId": "calendar-mappings-delete", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "mapping rule ID", "name": "mapping_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/integrations/calendar/setup": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Connect a new calendar integration.", "produces": [ "text/plain" ], "tags": [ "calendar" ], "summary": "Setup calendar integration", "operationId": "calendar-integrations-setup", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "Calendar service provider which the calendars will be retrieved", "name": "provider", "in": "query", "required": true }, { "type": "string", "description": "Page to which the user will be redirected after authenticating", "name": "return_to", "in": "query" } ], "responses": { "302": { "description": "Redirect to oAuth URL", "schema": { "type": "string" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "status payment required: integration already exists", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/integrations/calendar/{integration_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "List calendars for a particular integration, i.e. the calendars available from the connected account.", "produces": [ "text/plain" ], "tags": [ "calendar" ], "summary": "List calendars for a particular integration", "operationId": "calendar-integrations-calendars", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "integration ID", "name": "integration_id", "in": "path", "required": true } ], "responses": { "200": { "description": "List of calendars", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Calendar" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Delete a calendar integration.", "produces": [ "text/plain" ], "tags": [ "calendar" ], "summary": "Delete a calendar integration", "operationId": "calendar-integration-delete", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "integration ID", "name": "integration_id", "in": "path", "required": true }, { "type": "boolean", "description": "When true, leave linked entities in place. Default false: future-planned calendar time entries are soft-deleted asynchronously; tasks and time blocks are retained.", "name": "preserve_entities", "in": "query" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/integrations/calendar/{integration_id}/calendars/{calendar_id}": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Update calendar integration.", "produces": [ "text/plain" ], "tags": [ "calendar" ], "summary": "Update calendar integration", "operationId": "calendar-integrations-update-calendar", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "integration ID", "name": "integration_id", "in": "path", "required": true }, { "type": "integer", "description": "calendar ID", "name": "calendar_id", "in": "path", "required": true }, { "description": "Calendar object", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/models.Calendar" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/integrations/calendar/{integration_id}/calendars/{calendar_id}/settings": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Replaces the per-calendar settings for the given (user, calendar) pair. Idempotent PUT. Currently accepts hidden_event ical_uids; the payload will grow as more per-calendar settings are introduced.", "consumes": [ "application/json" ], "tags": [ "calendar" ], "summary": "Update per-calendar settings", "operationId": "calendar-integrations-update-calendar-settings", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "integration ID", "name": "integration_id", "in": "path", "required": true }, { "type": "integer", "description": "calendar ID", "name": "calendar_id", "in": "path", "required": true }, { "description": "Calendar settings payload", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/calendar.calendarSettingsRequest" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request or validation failure", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/integrations/calendar/{integration_id}/reauth": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Re-request authorization for an existing calendar integration, refreshing its token. By\ndefault this also escalates to write scope (the \"sync everywhere\" upgrade flow); pass\npreserve_scope=true to re-request the integration's existing scopes instead.", "produces": [ "text/plain" ], "tags": [ "calendar" ], "summary": "Re-authorize calendar integration.", "operationId": "calendar-integrations-reauth", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "integration ID", "name": "integration_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "Page to which the user will be redirected after authenticating", "name": "return_to", "in": "query", "required": true }, { "type": "boolean", "description": "Re-request the integration's existing scopes instead of escalating to write", "name": "preserve_scope", "in": "query" } ], "responses": { "302": { "description": "Redirect to oAuth URL", "schema": { "type": "string" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Integration not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/integrations/calendar/{integration_id}/update": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Update integration.", "produces": [ "text/plain" ], "tags": [ "calendar" ], "summary": "Update integration", "operationId": "calendar-integrations-update", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "integration ID", "name": "integration_id", "in": "path", "required": true }, { "type": "boolean", "description": "Override the auto-track default stamped onto newly materialized calendars. Defaults to false when omitted.", "name": "focus_auto_track_default", "in": "query" } ], "responses": { "200": { "description": "List of calendars", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Calendar" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/labor-costs/projects/users/rates": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "List all project-user labor cost rates filtered by project, user, or date (at least one filter is required)", "operationId": "get-all-project-user-labor-cost-rates", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by project IDs (max 200)", "name": "project_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by user IDs (max 200)", "name": "user_id", "in": "query" }, { "type": "string", "format": "date", "description": "filter to rates effective on this date", "name": "date", "in": "query" }, { "type": "array", "items": { "enum": [ "start_date", "-start_date", "end_date", "-end_date", "hourly_rate", "-hourly_rate", "currency", "-currency", "entity_id", "-entity_id" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/rate.RateWithEntityAPI" } } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/labor-costs/projects/{project_id}/rates": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "List project labor cost rates", "operationId": "get-project-labor-cost-rates", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "array", "items": { "enum": [ "start_date", "-start_date", "end_date", "-end_date", "hourly_rate", "-hourly_rate", "currency", "-currency" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/rate.RateAPI" } } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "Create or update a project labor cost rate", "operationId": "upsert-project-labor-cost-rate", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "description": "Rate payload (hourly_rate in smallest currency unit)", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rate.NewRatePayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/rate.RateAPI" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "Delete project labor cost rates in a date range", "operationId": "delete-project-labor-cost-rate-range", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "string", "format": "date", "description": "start date (YYYY-MM-DD)", "name": "from", "in": "query", "required": true }, { "type": "string", "format": "date", "description": "end date (YYYY-MM-DD)", "name": "to", "in": "query" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/labor-costs/projects/{project_id}/rates/check": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "Check conflicts for a project labor cost rate", "operationId": "check-project-labor-cost-conflicts", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "description": "Proposed rate", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rate.NewRatePayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/rate.ConflictCheckResult" } }, "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/labor-costs/projects/{project_id}/users/{user_id}/rates": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "List project-user labor cost rates", "operationId": "get-project-user-labor-cost-rates", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "integer", "description": "target user ID", "name": "user_id", "in": "path", "required": true }, { "type": "array", "items": { "enum": [ "start_date", "-start_date", "end_date", "-end_date", "hourly_rate", "-hourly_rate", "currency", "-currency" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/rate.RateAPI" } } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "Create or update a project-user labor cost rate", "operationId": "upsert-project-user-labor-cost-rate", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "integer", "description": "target user ID", "name": "user_id", "in": "path", "required": true }, { "description": "Rate payload (hourly_rate in smallest currency unit)", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rate.NewRatePayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/rate.RateAPI" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "Delete project-user labor cost rates in a date range", "operationId": "delete-project-user-labor-cost-rate-range", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "integer", "description": "target user ID", "name": "user_id", "in": "path", "required": true }, { "type": "string", "format": "date", "description": "start date (YYYY-MM-DD)", "name": "from", "in": "query", "required": true }, { "type": "string", "format": "date", "description": "end date (YYYY-MM-DD)", "name": "to", "in": "query" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/labor-costs/projects/{project_id}/users/{user_id}/rates/check": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "Check conflicts for a project-user labor cost rate", "operationId": "check-project-user-labor-cost-conflicts", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "integer", "description": "target user ID", "name": "user_id", "in": "path", "required": true }, { "description": "Proposed rate", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rate.NewRatePayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/rate.ConflictCheckResult" } }, "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/labor-costs/rates/{rate_id}": { "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "Delete a single labor cost rate by ID", "operationId": "delete-labor-cost-rate-by-id", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "rate ID", "name": "rate_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/labor-costs/users/rates": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "List all workspace-user labor cost rates", "operationId": "get-all-workspace-user-labor-cost-rates", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by user IDs", "name": "user_id", "in": "query" }, { "type": "array", "items": { "enum": [ "start_date", "-start_date", "end_date", "-end_date", "hourly_rate", "-hourly_rate", "currency", "-currency", "entity_id", "-entity_id" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/rate.RateWithEntityAPI" } } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/labor-costs/users/{user_id}/rates": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "List user labor cost rates in a workspace", "operationId": "get-workspace-user-labor-cost-rates", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "target user ID", "name": "user_id", "in": "path", "required": true }, { "type": "array", "items": { "enum": [ "start_date", "-start_date", "end_date", "-end_date", "hourly_rate", "-hourly_rate", "currency", "-currency" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/rate.RateAPI" } } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "Create or update a user labor cost rate in a workspace", "operationId": "upsert-workspace-user-labor-cost-rate", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "target user ID", "name": "user_id", "in": "path", "required": true }, { "description": "Rate payload (hourly_rate in smallest currency unit)", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rate.NewRatePayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/rate.RateAPI" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "Delete user labor cost rates in a workspace date range", "operationId": "delete-workspace-user-labor-cost-rate-range", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "target user ID", "name": "user_id", "in": "path", "required": true }, { "type": "string", "format": "date", "description": "start date (YYYY-MM-DD)", "name": "from", "in": "query", "required": true }, { "type": "string", "format": "date", "description": "end date (YYYY-MM-DD)", "name": "to", "in": "query" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/labor-costs/users/{user_id}/rates/check": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "Check conflicts for a user labor cost rate in a workspace", "operationId": "check-workspace-user-labor-cost-conflicts", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "target user ID", "name": "user_id", "in": "path", "required": true }, { "description": "Proposed rate", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rate.NewRatePayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/rate.ConflictCheckResult" } }, "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/labor-costs/workspace/rates": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the timeline of labor cost rates for the workspace.", "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "List workspace labor cost rates", "operationId": "get-workspace-labor-cost-rates", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "enum": [ "start_date", "-start_date", "end_date", "-end_date", "hourly_rate", "-hourly_rate", "currency", "-currency" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/rate.RateAPI" } } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Upserts a labor cost rate for the workspace.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "Create or update a workspace labor cost rate", "operationId": "upsert-workspace-labor-cost-rate", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Rate payload (hourly_rate in smallest currency unit)", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rate.NewRatePayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/rate.RateAPI" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes workspace labor cost rates within the given date range.", "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "Delete workspace labor cost rates in a date range", "operationId": "delete-workspace-labor-cost-rate-range", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "format": "date", "description": "start date (YYYY-MM-DD)", "name": "from", "in": "query", "required": true }, { "type": "string", "format": "date", "description": "end date (YYYY-MM-DD)", "name": "to", "in": "query" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/labor-costs/workspace/rates/check": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Dry-run: returns what existing rates would be modified or deleted by the proposed rate, without persisting.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "labor-costs" ], "summary": "Check conflicts for a workspace labor cost rate", "operationId": "check-workspace-labor-cost-conflicts", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Proposed rate", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rate.NewRatePayload" } } ], "responses": { "200": { "description": "Conflicts detected", "schema": { "$ref": "#/definitions/rate.ConflictCheckResult" } }, "204": { "description": "No conflicts" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/project-margin-targets": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns every project margin target set in the workspace (one row per project; a null project_id is the workspace default).", "produces": [ "application/json" ], "tags": [ "project-margin-targets" ], "summary": "List project margin targets", "operationId": "list-project-margin-targets", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Margin targets", "schema": { "type": "array", "items": { "$ref": "#/definitions/projectmargintarget.ListItem" } } }, "402": { "description": "Plan does not include project dashboards", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/project-margin-targets/workspace": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the workspace-level margin target. Both fields are null when nothing is set.", "produces": [ "application/json" ], "tags": [ "project-margin-targets" ], "summary": "Get the workspace margin target", "operationId": "get-workspace-project-margin-target", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Margin target (target_percent/scope null when unset)", "schema": { "$ref": "#/definitions/projectmargintarget.Response" } }, "402": { "description": "Plan does not include project dashboards", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates or replaces the workspace-level margin target (target_percent 1-100).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "project-margin-targets" ], "summary": "Set the workspace margin target", "operationId": "set-workspace-project-margin-target", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Margin target payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/projectmargintarget.SetPayload" } } ], "responses": { "200": { "description": "Margin target set", "schema": { "$ref": "#/definitions/projectmargintarget.Response" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Plan does not include project dashboards", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Removes the workspace-level margin target.", "tags": [ "project-margin-targets" ], "summary": "Clear the workspace margin target", "operationId": "clear-workspace-project-margin-target", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "402": { "description": "Plan does not include project dashboards", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/project-margin-targets/{project_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the project's margin target, falling back to the workspace default. Both fields are null when nothing is set.", "produces": [ "application/json" ], "tags": [ "project-margin-targets" ], "summary": "Get a project's margin target", "operationId": "get-project-margin-target", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Margin target (target_percent/scope null when unset)", "schema": { "$ref": "#/definitions/projectmargintarget.Response" } }, "400": { "description": "Invalid project ID", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Plan does not include project dashboards", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates or replaces the project's margin target (target_percent 1-100).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "project-margin-targets" ], "summary": "Set a project's margin target", "operationId": "set-project-margin-target", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "description": "Margin target payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/projectmargintarget.SetPayload" } } ], "responses": { "200": { "description": "Margin target set", "schema": { "$ref": "#/definitions/projectmargintarget.Response" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Plan does not include project dashboards", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Removes the project's margin target (reverts to the workspace default or none).", "tags": [ "project-margin-targets" ], "summary": "Clear a project's margin target", "operationId": "clear-project-margin-target", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid project ID", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Plan does not include project dashboards", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of projects based on the provided workspace ID and filter params.", "consumes": [ "application/json" ], "produces": [ "application/json", "application/json" ], "tags": [ "projects" ], "summary": "List projects", "operationId": "list-projects", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "name", "-name", "client_id", "-client_id", "client_name", "-client_name", "parent_project_id", "-parent_project_id", "private", "-private", "active", "-active", "billable", "-billable", "created_at", "-created_at", "updated_at", "-updated_at", "toggl_user_id", "-toggl_user_id", "created_by_user", "pinned", "-pinned", "relevance", "-relevance" ], "type": "string" }, "collectionFormat": "csv", "description": "order by. Also accepts cf_\u003cid\u003e / -cf_\u003cid\u003e to sort by any active workspace custom field. Multi_select and users CF types sort by their canonicalized (sorted) value array, so projects sharing the same set cluster together.", "name": "order_by", "in": "query" }, { "type": "boolean", "description": "filter by only pinned tasks", "name": "pinned", "in": "query" }, { "type": "boolean", "description": "filter by archived state (true = archived only, false = active only, omit = active only, empty = all projects)", "name": "archived", "in": "query" }, { "type": "boolean", "description": "filter by completion state (true = completed only, false = non-completed only, empty = all projects, omit = non-completed only, or all projects when archived=true)", "name": "completed", "in": "query" }, { "type": "boolean", "description": "filter by project privacy (true for private, false for public)", "name": "private", "in": "query" }, { "type": "string", "description": "filter by project name or client name", "name": "name", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by client IDs", "name": "client_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by project creator id", "name": "creator_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by tag IDs", "name": "tag_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by assignee user IDs; pass empty value (?assignee_user_id=) to include projects without user assignees", "name": "assignee_user_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by project IDs", "name": "project_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "return only projects accessible by the given users (requires manage workspace users when inspecting another user). Incompatible with only_me.", "name": "user_id", "in": "query" }, { "type": "boolean", "description": "return public projects union projects the current user is a member of (Track-shaped timer/picker scope; suppresses admin view_private_projects full-access and locked-private upsell during access resolution; still honors view_public_projects). Incompatible with user_id.", "name": "only_me", "in": "query" }, { "type": "boolean", "description": "includes the projects' rate data", "name": "include_rates", "in": "query" }, { "type": "boolean", "description": "computes and returns rollover_mins on each recurring instance (off by default — opt in only when the FE displays rollover, since per-chain hydration costs an extra OLTP + 2 warehouse queries)", "name": "include_rollover", "in": "query" }, { "type": "boolean", "description": "surface recurring templates (rrule != null) that have no live, uncompleted instance — i.e. either never materialized or every prior instance is already completed. Off by default. Useful for letting the user start the next period after dropping auto-first-instance materialization.", "name": "include_idle_recurring_templates", "in": "query" }, { "type": "boolean", "description": "include draft projects in the response (default false hides them; requires view_draft_projects permission)", "name": "include_drafts", "in": "query" }, { "type": "boolean", "description": "include the workspace's private projects read-only for role-entitled users whose plan lacks the private-projects feature (upsell flow). Their activity figures are blurred to zero. Off by default; other consumers never see private projects they can't otherwise access.", "name": "include_locked_private", "in": "query" }, { "type": "string", "format": "date", "description": "filter projects overlapping date range (start). Used with end_date to find projects where project.start_date \u003c= end_date AND project.end_date \u003e= start_date", "name": "start_date", "in": "query" }, { "type": "string", "format": "date", "description": "filter projects overlapping date range (end). Used with start_date to find projects where project.start_date \u003c= end_date AND project.end_date \u003e= start_date", "name": "end_date", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use start_date instead", "name": "date_overlap_start", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use end_date instead", "name": "date_overlap_end", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "filter by custom field values (format: fieldID:value1,value2)", "name": "cf_filter", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.PageWithTotal-models_ProjectWithAggregations" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new project with the provided name, workspace ID, parent project ID, and client ID.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Create a new project", "operationId": "create-project", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Project payload", "name": "project", "in": "body", "required": true, "schema": { "$ref": "#/definitions/project.Payload" } } ], "responses": { "201": { "description": "Project created successfully", "schema": { "$ref": "#/definitions/models.Project" } }, "400": { "description": "Invalid project parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/bulk": { "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes multiple projects and their children by the provided IDs. Best-effort: individual failures are logged but do not abort the batch.", "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Bulk delete projects", "operationId": "bulk-delete-projects", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "project IDs to delete", "name": "ids", "in": "query", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Partially updates multiple projects", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Bulk partial update projects", "operationId": "bulk-partial-update-projects", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Array of project partial updates", "name": "projects", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/project.PartialUpdatePayloadWithID" } } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/bulk/archive": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Archives multiple projects and their children by the provided IDs. Best-effort: individual failures are logged but do not abort the batch.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Bulk archive projects", "operationId": "bulk-archive-projects", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Bulk archive payload", "name": "bulkArchivePayload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/project.BulkArchivePayload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/bulk/restore": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Restores multiple projects by the provided IDs. Best-effort: individual failures are logged but do not abort the batch.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Bulk restore projects", "operationId": "bulk-restore-projects", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Bulk restore payload", "name": "bulkRestorePayload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/project.BulkRestorePayload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/bulk/unarchive": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Unarchives multiple projects by the provided IDs. Best-effort: individual failures are logged but do not abort the batch.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Bulk unarchive projects", "operationId": "bulk-unarchive-projects", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Bulk unarchive payload", "name": "bulkUnarchivePayload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/project.BulkUnarchivePayload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/groups/{group}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns projects grouped by a built-in dimension (client, creator, tag, parent_project, assignee) or a custom field (cf:{fieldID}). CF groups include color and position fields on each group envelope. total_distinct is populated for tag, assignee, and multi_select CF; omitted for select CF (each project belongs to at most one option). order_by is not supported for cf dimensions.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "project-groups" ], "summary": "Gets projects in groups", "operationId": "get-project-groups", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "group dimension (built-in: client, creator, tag, parent_project, assignee; custom field: cf:{fieldID})", "name": "group", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "group_name", "-group_name" ], "type": "string" }, "collectionFormat": "csv", "description": "order groups by", "name": "order_by", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "order projects within each group", "name": "project_order_by", "in": "query" }, { "type": "integer", "description": "max projects per group (1–100); always returns page 1 per group — to page deeper use the flat project list with the same filters", "name": "projects_per_group", "in": "query" }, { "type": "boolean", "description": "include total project count per group (default true when projects_per_group is set)", "name": "include_group_totals", "in": "query" }, { "type": "boolean", "description": "include a synthetic bucket for projects with no group entity; default false, always rendered last", "name": "include_unassigned", "in": "query" }, { "type": "boolean", "description": "filter by archived state", "name": "archived", "in": "query" }, { "type": "boolean", "description": "filter by project privacy", "name": "private", "in": "query" }, { "type": "string", "description": "filter by project name or client name", "name": "name", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by client IDs", "name": "client_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by project creator IDs", "name": "creator_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by tag IDs", "name": "tag_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by parent project IDs", "name": "parent_project_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by assignee user IDs", "name": "assignee_user_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by project IDs", "name": "project_id", "in": "query" }, { "type": "string", "format": "date", "description": "filter projects overlapping date range (start)", "name": "start_date", "in": "query" }, { "type": "string", "format": "date", "description": "filter projects overlapping date range (end)", "name": "end_date", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "return only projects accessible by the given users (requires manage workspace users when inspecting another user). Incompatible with only_me.", "name": "user_id", "in": "query" }, { "type": "boolean", "description": "return public projects union projects the current user is a member of (Track-shaped timer/picker scope; suppresses admin view_private_projects full-access during access resolution; still honors view_public_projects). Incompatible with user_id.", "name": "only_me", "in": "query" }, { "type": "boolean", "description": "include draft projects in the response (default false hides them; requires view_draft_projects permission)", "name": "include_drafts", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "filter by custom field values (format: fieldID:value1,value2)", "name": "cf_filter", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/projectgroup.projectGroupsResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Feature not available", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/members": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns lists of userIDs and groupIDs for each given project.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "List members for multiple projects", "operationId": "list-batch-projects-members", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "project IDs", "name": "ids", "in": "query", "required": true } ], "responses": { "200": { "description": "List of project members per project", "schema": { "type": "array", "items": { "$ref": "#/definitions/projectuser.ProjectMembers" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/rates": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a summary list of rates for a given project.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "rates" ], "summary": "List project rates summary", "operationId": "list-project-rates-summary", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "Number of items per page (default: 50, max: 100).", "name": "rows", "in": "query" }, { "type": "string", "description": "Field and direction to sort by, formatted as 'field,direction'. Fields: 'project_name', 'hourly_rate', 'start_at', 'end_at'. Defaults to 'project_name,asc' if not given.", "name": "order_by", "in": "query" }, { "type": "string", "description": "Project name to search for. Is a contains-anywhere search", "name": "search", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/page.Envelope-models_EffectiveProjectRatesSummary" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/templates": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of template projects.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "List project templates", "operationId": "list-project-templates", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "string", "description": "filter by name", "name": "name", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" }, { "type": "boolean", "description": "filter by archived state (true = archived only, false = active only, omit = active only, empty = all templates)", "name": "archived", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.PageWithTotal-models_ProjectWithAggregations" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a project by the provided ID.", "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Get a project by ID", "operationId": "get-project", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.ProjectWithAggregations" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Update an existing project", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Update project", "operationId": "update-project", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Project ID", "name": "project_id", "in": "path", "required": true }, { "description": "Project payload", "name": "project", "in": "body", "required": true, "schema": { "$ref": "#/definitions/project.Payload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes a project by the provided ID.", "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Delete a project by ID", "operationId": "delete-project", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Partially update an existing project", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Patch project", "operationId": "patch-project", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Project ID", "name": "project_id", "in": "path", "required": true }, { "description": "Project payload", "name": "project", "in": "body", "required": true, "schema": { "$ref": "#/definitions/project.PartialUpdatePayload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/archive": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Archives a project by the provided ID.", "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Archives a project by ID", "operationId": "archive-project", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/attachments": { "get": { "description": "Returns a list of project-attachments based on the provided workspace ID, project ID and filter params.", "produces": [ "application/json" ], "tags": [ "project-attachments" ], "summary": "List project attachments", "operationId": "list-project-attachments", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "array", "items": { "enum": [ "created_at", "-created_at", "display_order", "-display_order" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.ProjectAttachment" } } }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } }, "post": { "description": "Creates a new project attachment with the provided name and workspace ID.", "produces": [ "application/json" ], "tags": [ "project-attachments" ], "summary": "Create a new project attachment", "operationId": "create-project-attachment", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "string", "description": "Project attachment name", "name": "name", "in": "formData" }, { "type": "number", "description": "Project attachment display order", "name": "display_order", "in": "formData", "required": true }, { "type": "file", "description": "attachment file", "name": "file", "in": "formData", "required": true } ], "responses": { "201": { "description": "Project attachment created successfully", "schema": { "$ref": "#/definitions/models.ProjectAttachment" } }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/attachments/bulk": { "post": { "description": "Creates up to 10 project attachments in a single request. All-or-nothing: if any file fails, none are created.", "produces": [ "application/json" ], "tags": [ "project-attachments" ], "summary": "Create project attachments in bulk", "operationId": "bulk-create-project-attachments", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "file" }, "collectionFormat": "csv", "description": "attachment files (max 10)", "name": "files", "in": "formData", "required": true }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "names for each file, indexed as names[0], names[1], etc.", "name": "names", "in": "formData" }, { "type": "array", "items": { "type": "number" }, "collectionFormat": "csv", "description": "display orders for each file, indexed as display_orders[0], display_orders[1], etc.", "name": "display_orders", "in": "formData", "required": true } ], "responses": { "201": { "description": "Project attachments created successfully", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.ProjectAttachment" } } }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/attachments/{attachment_id}": { "put": { "description": "Update an existing project attachment", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "project-attachments" ], "summary": "Update project attachment", "operationId": "update-project-attachment", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "string", "description": "ProjectAttachment ID", "name": "attachment_id", "in": "path", "required": true }, { "description": "ProjectAttachment payload", "name": "projectAttachment", "in": "body", "required": true, "schema": { "$ref": "#/definitions/projectattachment.Payload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "404": { "description": "Project attachment does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } }, "delete": { "description": "Deletes a project attachment by the provided ID.", "produces": [ "application/json" ], "tags": [ "project-attachments" ], "summary": "Delete a project attachment by ID", "operationId": "delete-project-attachment", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "integer", "description": "project attachment ID", "name": "attachment_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "404": { "description": "Project attachment does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/attachments/{attachment_id}/view": { "get": { "description": "View a project attachment by the provided ID.", "produces": [ "application/octet-stream", "image/png", "image/jpeg", "application/pdf" ], "tags": [ "project-attachments" ], "summary": "View a project attachment", "operationId": "view-project-attachment", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "integer", "description": "project attachment ID", "name": "attachment_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.ProjectAttachment" } }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "404": { "description": "ProjectAttachment does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/children": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a project and its children sub-projects by the provided ID.", "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Get a project with its children sub-projects by ID", "operationId": "get-project-with-children", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "name", "-name", "client_id", "-client_id", "parent_project_id", "-parent_project_id", "private", "-private", "active", "-active", "billable", "-billable", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Page-models_ProjectWithAggregations" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/complete": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Sets completed_at to the current time when not already set; idempotent. When the project is an instance of a recurring template, also materializes (or resolves the pre-created) next instance after the completed period. Templates themselves cannot be completed.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Mark a project as completed", "operationId": "complete-project", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/project.CompleteProjectResponse" } }, "400": { "description": "Project is a template, or recurrence rule is invalid", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/create-from-template": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Clones a template project into a new regular project with all tasks and fixed fee.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Create a project from a template", "operationId": "create-project-from-template", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "template project ID", "name": "project_id", "in": "path", "required": true }, { "description": "Optional overrides for the new project", "name": "payload", "in": "body", "schema": { "$ref": "#/definitions/project.CreateFromTemplatePayload" } } ], "responses": { "201": { "description": "Project created successfully", "schema": { "$ref": "#/definitions/models.Project" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Template not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/create-template": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Clones an existing project into a new template. Original project is not modified.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Create a template from an existing project", "operationId": "create-template-from-project", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "source project ID", "name": "project_id", "in": "path", "required": true }, { "description": "Optional overrides for the new template", "name": "payload", "in": "body", "schema": { "$ref": "#/definitions/project.CreateTemplateFromProjectPayload" } } ], "responses": { "201": { "description": "Template created successfully", "schema": { "$ref": "#/definitions/models.Project" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/duplicate": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Duplicates a project and its tasks. Optionally accepts a new name for the duplicated project.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Duplicate a project", "operationId": "duplicate-project", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "description": "Optional duplicate payload", "name": "payload", "in": "body", "schema": { "$ref": "#/definitions/project.DuplicatePayload" } } ], "responses": { "201": { "description": "Project duplicated successfully", "schema": { "$ref": "#/definitions/models.Project" } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/duplicate-template": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates an independent copy of a template project, preserving all associated data (tasks, rates, milestones, attachments). The clone remains a template.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Duplicate a template project", "operationId": "duplicate-template", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "source template project ID", "name": "project_id", "in": "path", "required": true }, { "description": "Optional overrides", "name": "payload", "in": "body", "schema": { "$ref": "#/definitions/project.DuplicatePayload" } } ], "responses": { "201": { "description": "Template duplicated successfully", "schema": { "$ref": "#/definitions/models.Project" } }, "400": { "description": "Invalid request or source is not a template", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Template not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/instances": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the materialized recurring-project instances for the given template, ordered by start_date ASC by default.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "List instances of a recurring project template", "operationId": "list-recurring-project-instances", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "recurring template project ID", "name": "project_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" }, { "type": "string", "format": "date", "description": "filter instances overlapping the date range (must be supplied together with end_date)", "name": "start_date", "in": "query" }, { "type": "string", "format": "date", "description": "filter instances overlapping the date range (must be supplied together with start_date)", "name": "end_date", "in": "query" }, { "type": "boolean", "description": "computes and returns rollover_mins on each instance (off by default — opt in only when the FE displays rollover, since chain hydration costs an extra OLTP + 2 warehouse queries)", "name": "include_rollover", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.PageWithTotal-models_ProjectWithAggregations" } }, "400": { "description": "Project is not a template, template has no recurrence rule, or invalid date range", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Template not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/instances/{date}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the materialized instance for the period containing the supplied date. 404 when the date falls in a valid period of the rule but no instance has been materialized yet. 400 when the date doesn't fit any period of the rule.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Get a recurring project instance by start date", "operationId": "get-recurring-project-instance", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "recurring template project ID", "name": "project_id", "in": "path", "required": true }, { "type": "string", "format": "date", "description": "date inside the desired period", "name": "date", "in": "path", "required": true } ], "responses": { "200": { "description": "Materialized instance for the period", "schema": { "$ref": "#/definitions/models.Project" } }, "400": { "description": "Project is not a template, template has no recurrence rule, or date does not fit any period of the rule", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Template not found, or instance for this period has not been materialized yet", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Materializes the period containing the supplied date for a recurring template. Idempotent — returns 200 if a live instance for the period already exists, 201 if newly created. The body carries optional per-instance overrides; an empty body is fine. The response includes projection_revision (compare before replaying pending edits; mismatch =\u003e refetch) and task_id_by_template_task_id (template task id -\u003e live task id).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Materialize a recurring project instance for a given date", "operationId": "create-recurring-project-instance", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "recurring template project ID", "name": "project_id", "in": "path", "required": true }, { "type": "string", "format": "date", "description": "date inside the desired period", "name": "date", "in": "path", "required": true }, { "description": "Optional per-instance overrides", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/project.CreateInstancePayload" } } ], "responses": { "200": { "description": "Existing instance for the period", "schema": { "$ref": "#/definitions/project.CreateInstanceResult" } }, "201": { "description": "Newly materialized instance", "schema": { "$ref": "#/definitions/project.CreateInstanceResult" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Template not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Concurrent modification", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/make-public": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Converts a private project (and its subtree) to public. Free alternative to the private-projects upsell: a plan-blocked admin shown a private project read-only can convert it to public to use it on the current plan instead of upgrading. The conversion is one-way for a plan-blocked workspace (making a project private again is feature-gated).", "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Make a project public", "operationId": "make-project-public", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/members": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of userIDs and groupIDs that are part of the given project.", "consumes": [ "application/json" ], "produces": [ "application/json", "application/json" ], "tags": [ "projects" ], "summary": "List project memmbers", "operationId": "list-projects-members", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "200": { "description": "List of project members", "schema": { "$ref": "#/definitions/projectuser.ProjectMembers" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Updates the role of a project member (user or group).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Update project member role", "operationId": "update-member-role", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "description": "Member and new role", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/projectuser.updateMemberRole" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Adds users and groups to the given project.", "consumes": [ "application/json" ], "produces": [ "application/json", "application/json" ], "tags": [ "projects" ], "summary": "Add project members", "operationId": "add-project-members", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "description": "Project members to add", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/projectuser.PostProjectMembers" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Removes a single user or group from the given project.", "consumes": [ "application/json" ], "produces": [ "application/json", "application/json" ], "tags": [ "projects" ], "summary": "Remove project member", "operationId": "remove-project-member", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "description": "Project member to remove", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/projectuser.deleteProjectMember" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/parents": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a project and its parent projects by the provided ID.", "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Get a project with its parent projects by ID", "operationId": "get-project-with-parents", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "name", "-name", "client_id", "-client_id", "parent_project_id", "-parent_project_id", "private", "-private", "active", "-active", "billable", "-billable", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Page-models_Project" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/pinned": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Pins a project by the provided ID.", "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Pin a project by ID", "operationId": "pin-project", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Unpins a project by the provided ID.", "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Unpin a project by ID", "operationId": "unpin-project", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/rates": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a merged timeline of workspace and project rates for a given project. Project rates take precedence over workspace rates for overlapping periods.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "rates" ], "summary": "List project rates", "operationId": "list-project-rates", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "string", "description": "Field and direction to sort by, formatted as 'field,direction'. Fields: 'hourly_rate', 'start_at', 'end_at'. Defaults to 'start_at,asc' if not given.", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/project.RateAPI" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new rate for a given project.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "rates" ], "summary": "Create a project rate", "operationId": "create-project-rate", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "description": "Rate payload", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/project.NewRate" } } ], "responses": { "201": { "description": "Rate created successfully", "schema": { "$ref": "#/definitions/models.Rate" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes a project rate within a given time range.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "rates" ], "summary": "Delete a project rate", "operationId": "delete-project-rate", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true }, { "type": "string", "format": "date-time", "description": "start of the time range to delete (RFC3339)", "name": "from", "in": "query", "required": true }, { "type": "string", "format": "date-time", "description": "end of the time range to delete (RFC3339)", "name": "to", "in": "query", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/rates/current": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "rates" ], "summary": "Get the current rate for a project if any.", "operationId": "get-current-project-rate", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/project.RateAPI" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/restore": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Restores a project by the provided ID.", "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Restore a project by ID", "operationId": "restore-project", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/unarchive": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Unarchives a project by the provided ID.", "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Unarchive a project by ID", "operationId": "unarchive-project", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/projects/{project_id}/uncomplete": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Inverse of /complete — sets completed_at to NULL. Idempotent. No recurring side-effect: any next instance materialized by a prior completion stays in place as a normal instance. Templates and archived projects are rejected (mirrors /complete).", "produces": [ "application/json" ], "tags": [ "projects" ], "summary": "Clear the completed flag on a project", "operationId": "uncomplete-project", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.Project" } }, "400": { "description": "Project is a template or archived", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Project not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/recurring-budget-suggestions/{project_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "recurring-budget-suggestions" ], "summary": "Get recurring-project budget suggestion", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Recurring template project ID", "name": "project_id", "in": "path", "required": true }, { "type": "string", "description": "Target period start (YYYY-MM-DD)", "name": "target_period_start", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/recurringbudget.suggestionResponse" } }, "204": { "description": "No suggestion to surface" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/recurring-budget-suggestions/{project_id}/accept": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "tags": [ "recurring-budget-suggestions" ], "summary": "Accept a recurring-project budget suggestion", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Recurring template project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "204": { "description": "Decision recorded" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "No current suggestion", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/recurring-budget-suggestions/{project_id}/dismiss": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "tags": [ "recurring-budget-suggestions" ], "summary": "Dismiss a recurring-project budget suggestion", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Recurring template project ID", "name": "project_id", "in": "path", "required": true } ], "responses": { "204": { "description": "Decision recorded" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "No current suggestion", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/search": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Searches time entries by description, tasks by name, and projects by name.\nReturns grouped results for autocomplete use cases. Time entries include results\nwhere the linked task has been soft-deleted (task fields will be null).\nTime entries are always scoped to the authenticated user.\nTime entry tag data is populated only when group_by_tags is true, which also\nsplits suggestions that share a description and task but differ in tags.\nWithout it tag_ids is null and tags is empty on every time entry result.\nDeduplication across the time_entries and tasks groups is best-effort: a time\nentry is dropped when its task already appears in the tasks group, and because\nboth groups are limited by per_group first, the drop is not backfilled.\nKeywords longer than 255 characters are truncated. Min 3 characters required.", "produces": [ "application/json" ], "tags": [ "search" ], "summary": "Unified search across time entries, tasks, and projects", "operationId": "search", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "Search term, min 3 characters", "name": "keyword", "in": "query", "required": true }, { "type": "integer", "description": "Max results per group (1-10, default 5)", "name": "per_group", "in": "query" }, { "type": "integer", "description": "Scope tasks to this assignee", "name": "assignee_user_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Also match tasks assigned to these teams; combined with assignee_user_id as an OR", "name": "assignee_team_id", "in": "query" }, { "type": "integer", "description": "Scope time-entry and task suggestions to this project", "name": "project_id", "in": "query" }, { "type": "integer", "description": "Scope time-entry (description) suggestions to this task", "name": "task_id", "in": "query" }, { "type": "boolean", "description": "Include draft projects and tasks in the search results", "name": "include_drafts", "in": "query" }, { "type": "boolean", "description": "Exclude external calendar-derived tasks and time entries", "name": "exclude_calendar_events", "in": "query" }, { "type": "boolean", "description": "Populate time entry tag data and deduplicate by effective tag set as well", "name": "group_by_tags", "in": "query" }, { "type": "boolean", "description": "Scope the projects group to the projects the current user is assigned to, plus public projects when they hold view_public_projects (Track-shaped timer/picker scope; suppresses admin view_private_projects full-access). The time_entries and tasks groups are unaffected. Off by default.", "name": "only_me", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/search.Result" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "499": { "description": "Client closed the request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/search/mentions": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns up to per_group members, projects and tags matching the keyword,\nfor the Focus AI chat mention picker. The keyword is optional so a bare\ntrigger populates the picker; when omitted, each section returns its\nfirst per_group entries. member id is the user account id.\nThe three sources are independent: a source that fails is returned empty\nand named in the degraded array, and the endpoint fails only when all\nthree fail. Keywords longer than 255 characters are truncated.", "produces": [ "application/json" ], "tags": [ "search" ], "summary": "Autocomplete members, projects and tags for @-mentions", "operationId": "search-mentions", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "Search term (optional, max 255 characters)", "name": "keyword", "in": "query" }, { "type": "integer", "description": "Max results per group (1-10, default 3)", "name": "per_group", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/search.MentionsResult" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "499": { "description": "Client closed the request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/seed": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Generates fake data for the specified workspace", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "data-generator" ], "summary": "Generates fake data", "operationId": "data-generator-org", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Generator payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/datagenerator.Payload" } } ], "responses": { "204": { "description": "Successful operation", "schema": { "type": "string" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/subscriptions/upsert-forced-trial": { "post": { "description": "Creates or updates a trial for the organization based on workspace data and Plan import history.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "subscriptions" ], "summary": "Upserts a trial", "operationId": "upsert-forced-trial", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Optional plan workspace ID", "name": "request", "in": "body", "schema": { "$ref": "#/definitions/subscription.upsertForcedTrialRequest" } } ], "responses": { "200": { "description": "Trial was created or updated", "schema": { "$ref": "#/definitions/subscription.upsertForcedTrialResponse" } }, "204": { "description": "No trial created or updated (existing unchanged trial, paid subscription, or no eligible trial)" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Forced trial already exists or org has active subscription", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/task-suggestions": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "task-suggestions" ], "summary": "Get project suggestion for a task", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Request body", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/tasksuggestion.suggestPayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/tasksuggestion.suggestionResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/task-suggestions/bulk": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "task-suggestions" ], "summary": "Get project suggestions for multiple tasks", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Request body", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/tasksuggestion.suggestBulkPayload" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/tasksuggestion.suggestionResponse" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of tasks based on the workspace ID.", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "List tasks", "operationId": "list-tasks", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "boolean", "description": "include time entries", "name": "with_entries", "in": "query" }, { "type": "boolean", "description": "filter by pinned state", "name": "pinned", "in": "query" }, { "type": "array", "items": { "enum": [ "user_id", "-user_id", "project_id", "-project_id", "parent_task_id", "-parent_task_id", "name", "-name", "estimated_mins", "-estimated_mins", "priority", "-priority", "priority_at", "-priority_at", "start_date", "-start_date", "end_date", "-end_date", "status_id", "-status_id", "pinned", "-pinned", "created_at", "-created_at", "updated_at", "-updated_at", "last_activity", "-last_activity", "position", "-position", "timeblock_start", "-timeblock_start", "timeblock_now_diff", "-timeblock_now_diff", "billable", "-billable", "relevance", "-relevance", "tag_ids", "-tag_ids", "assignees", "-assignees", "sub_tasks_grouped", "-sub_tasks_grouped" ], "type": "string" }, "collectionFormat": "csv", "description": "order by. tag_ids and assignees order by the canonicalized (sorted) array, so tasks with the same set of tags or assignees cluster together regardless of storage order. Also accepts pcf_\u003cid\u003e / -pcf_\u003cid\u003e to sort tasks by the named custom field on the task's parent project, and cf_\u003cid\u003e / -cf_\u003cid\u003e to sort by the task's own custom field. Multi_select and users CF types use the same canonicalized-array semantics. sub_tasks_grouped orders top-level tasks by name (direction applies) with each task's subtasks directly after it in position order; it cannot be combined with other order_by values.", "name": "order_by", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter in tasks by status' IDs", "name": "status_id", "in": "query" }, { "type": "integer", "description": "filter in tasks by user", "name": "toggl_user_id", "in": "query" }, { "type": "string", "description": "filter tasks by task name, project name, or client name", "name": "name", "in": "query" }, { "type": "boolean", "description": "filter tasks if it has time entries", "name": "has_time_entries", "in": "query" }, { "type": "boolean", "description": "filter tasks if it has time blocks", "name": "has_time_blocks", "in": "query" }, { "type": "boolean", "description": "filter tasks by date presence: true returns tasks with start_date or end_date, false returns tasks with both dates NULL", "name": "has_dates", "in": "query" }, { "type": "boolean", "description": "filter tasks by private state", "name": "private", "in": "query" }, { "type": "boolean", "description": "filter in/out archived tasks", "name": "archived", "in": "query" }, { "type": "boolean", "description": "include tasks whose parent project is completed (default false hides them; tasks without a project are always returned)", "name": "include_project_completed", "in": "query" }, { "type": "boolean", "description": "include tasks belonging to draft projects (default false hides them; requires view_draft_projects permission; tasks without a project are always returned)", "name": "include_drafts", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by project ids. `?project_id=` will include tasks with no project.", "name": "project_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by parent task ids. `?parent_task_id=` will include tasks with no parent.", "name": "parent_task_id", "in": "query" }, { "type": "string", "format": "date", "description": "filter tasks overlapping date range (start). Used with end_date to find tasks where task.start_date \u003c= end_date AND task.end_date \u003e= start_date", "name": "start_date", "in": "query" }, { "type": "string", "format": "date", "description": "filter tasks overlapping date range (end). Used with start_date to find tasks where task.start_date \u003c= end_date AND task.end_date \u003e= start_date", "name": "end_date", "in": "query" }, { "type": "string", "format": "date", "description": "filter tasks active by a date (today_and_overdue preset): returns tasks that have at least one date and whose start_date is null or on or before the date; end_date is not upper-bounded so overdue tasks remain included", "name": "active_by_date", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use start_date instead", "name": "start_date_from", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use start_date instead", "name": "start_date_to", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use end_date instead", "name": "end_date_from", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use end_date instead", "name": "end_date_to", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use start_date instead", "name": "dates_overlap_start", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use end_date instead", "name": "dates_overlap_end", "in": "query" }, { "type": "integer", "description": "filter by estimated mins min", "name": "estimated_mins_min", "in": "query" }, { "type": "integer", "description": "filter by estimated mins max", "name": "estimated_mins_max", "in": "query" }, { "type": "array", "items": { "enum": [ "plan", "focus", "google_calendar", "outlook_calendar" ], "type": "string" }, "collectionFormat": "csv", "description": "filter by sources", "name": "source", "in": "query" }, { "type": "array", "items": { "enum": [ "none", "low", "medium", "high" ], "type": "string" }, "collectionFormat": "csv", "description": "filter by priority", "name": "priority", "in": "query" }, { "type": "boolean", "description": "filter by whether task is a user priority", "name": "is_priority", "in": "query" }, { "type": "array", "items": { "enum": [ "timeblocked", "not_timeblocked", "tracked", "not_tracked", "active", "done" ], "type": "string" }, "collectionFormat": "csv", "description": "filter by state", "name": "state", "in": "query" }, { "type": "string", "format": "date-time", "description": "filter by a task's timeblock start date (from)", "name": "timeblock_start_from", "in": "query" }, { "type": "string", "format": "date-time", "description": "filter by a task's timeblock start date (until)", "name": "timeblock_start_until", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter in tasks by timeblock' IDs", "name": "time_block_id", "in": "query" }, { "type": "boolean", "description": "filter in tasks by completed timeblocks", "name": "time_block_completed", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter tasks by team IDs", "name": "team_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter in tasks assigned to these teams, without expanding the teams to their members", "name": "assignee_team_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter in tasks by assignee's user IDs", "name": "assignee_user_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter in tasks by tag IDs", "name": "tag_id", "in": "query" }, { "type": "boolean", "description": "filter by recurring tasks", "name": "recurring", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by recurring task ids", "name": "recurring_task_ids", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by client ids. `?client_id=` will include tasks with no client.", "name": "client_id", "in": "query" }, { "type": "boolean", "description": "includes the parent projects' rate data", "name": "include_rates", "in": "query" }, { "type": "boolean", "description": "includes the unified user and team assignees", "name": "include_assignees", "in": "query" }, { "type": "boolean", "description": "when true, the name filter also matches the parent task's name, returning subtasks whose parent matches", "name": "include_parent_matches", "in": "query" }, { "type": "boolean", "description": "when true, skips computing aggregations and parent task hydration for faster response", "name": "disable_aggregations", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "filter by the task's own custom field values. Repeatable; each entry is 'fieldID:value1,value2' (values within an entry are OR, separate entries AND). Trailing colon 'fieldID:' selects the no-value bucket (select/multi_select only). Predicate vocabulary mirrors the project list cf_filter.", "name": "cf_filter", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.PageWithTotal-task_TaskWithParentAndAggregations" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new task with the provided details.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Create a new task", "operationId": "create-task", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Task payload", "name": "task", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.CreatePayload" } } ], "responses": { "201": { "description": "Task created successfully", "schema": { "$ref": "#/definitions/models.Task" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/bulk": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates tasks in bulk with the provided details.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Creates tasks in bulk", "operationId": "bulk-create-task", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Tasks payload", "name": "tasks", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.BulkCreatePayload" } } ], "responses": { "201": { "description": "Tasks created successfully", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Task" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes tasks by the provided IDs.", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Delete tasks by ID", "operationId": "bulk-delete-task", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "task IDs", "name": "ids", "in": "query", "required": true }, { "type": "boolean", "description": "Conduct outbound sync or not", "name": "outbound_sync", "in": "query" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "description": "Partially update existing tasks in bulk", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Partially update tasks in bulk", "operationId": "bulk-patch-task", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Task payload with task ID", "name": "task", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/task.PartialUpdatePayloadWithID" } } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/bulk/archive": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Bulk archives tasks, and their children given their IDs", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Bulk archives tasks given their IDs", "operationId": "bulk-archive-task", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Task bulk archive payload", "name": "taskBulkArchive", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.BulkArchivePayload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Task not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/bulk/duplicate": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Duplicates one or more tasks. If specified, their children may be duplicated asynchronously.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Bulk duplicates tasks", "operationId": "bulk-duplicate-task", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Tasks payload", "name": "task", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.BulkDuplicatePayload" } } ], "responses": { "201": { "description": "Tasks duplicated successfully", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Task" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/bulk/restore": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Bulk restores tasks, and their children given their IDs", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Bulk restores tasks given their IDs", "operationId": "bulk-restore-task", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Task bulk restore payload", "name": "taskBulkRestore", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.BulkRestorePayload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Task not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/bulk/unarchive": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Bulk unarchives tasks, and their children given their IDs", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Bulk unarchives tasks given their IDs", "operationId": "bulk-unarchive-task", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Task bulk unarchive payload", "name": "taskBulkUnarchive", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.BulkUnarchivePayload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Task not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/by-external-id": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a task matching the given integration source and external ID.", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Get a task by external ID", "operationId": "get-task-by-external-id", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "integration source", "name": "source", "in": "query", "required": true }, { "type": "integer", "description": "external ID from the integration", "name": "ext_id", "in": "query", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Task" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Task not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/calendar": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns raw calendar events from all the user's connected calendars. Requires either date_from+date_to, or at least one calendar_event_id (or both).", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Get raw calendar events", "operationId": "get-tasks-calendar-events", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "from timestamp (RFC3339); required when calendar_event_id is not supplied", "name": "date_from", "in": "query" }, { "type": "string", "description": "to timestamp (RFC3339); required when calendar_event_id is not supplied", "name": "date_to", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "calendar event IDs to fetch; when supplied, date_from/date_to are optional", "name": "calendar_event_id", "in": "query" }, { "type": "boolean", "description": "If set, return only events whose hidden flag matches this value. Omit to return all events.", "name": "hidden", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/task.EventResponse" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Sync a list of tasks based on calendar events.", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Sync tasks by calendar range", "operationId": "put-tasks-calendar-range", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "from timestamp", "name": "date_from", "in": "query", "required": true }, { "type": "string", "description": "to timestamp", "name": "date_to", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/task.CalendarSyncSummary" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/groups/{group}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Gets tasks in groups depending on name", "produces": [ "application/json" ], "tags": [ "task-groups" ], "summary": "Gets tasks in groups", "operationId": "get-task-groups", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "enum": [ "projects", "users", "tags" ], "type": "string", "description": "group name", "name": "group", "in": "path", "required": true }, { "type": "array", "items": { "enum": [ "plan", "focus", "google_calendar", "outlook_calendar" ], "type": "string" }, "collectionFormat": "csv", "description": "filter by sources", "name": "source", "in": "query" }, { "enum": [ "none", "low", "medium", "high" ], "type": "string", "description": "filter by priority", "name": "priority", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by statuses", "name": "status_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by project IDs", "name": "project_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by client IDs", "name": "client_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by assignee user IDs", "name": "assignee_user_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by tag IDs", "name": "tag_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by team IDs (resolves to member user IDs)", "name": "team_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by assignee member-tag IDs (resolves to member user IDs)", "name": "user_tag_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by group IDs", "name": "group_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter in by creator IDs", "name": "creator_id", "in": "query" }, { "type": "string", "description": "filter in by task name", "name": "name", "in": "query" }, { "type": "string", "format": "date", "description": "filter tasks overlapping date range (start). Used with end_date to find tasks where task.start_date \u003c= end_date AND task.end_date \u003e= start_date", "name": "start_date", "in": "query" }, { "type": "string", "format": "date", "description": "filter tasks overlapping date range (end). Used with start_date to find tasks where task.start_date \u003c= end_date AND task.end_date \u003e= start_date", "name": "end_date", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use start_date instead", "name": "start_date_from", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use start_date instead", "name": "start_date_to", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use end_date instead", "name": "end_date_from", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use end_date instead", "name": "end_date_to", "in": "query" }, { "type": "boolean", "description": "filter by project privacy (true for private, false for public)", "name": "private", "in": "query" }, { "type": "boolean", "description": "filter groups with no tasks", "name": "exclude_empty", "in": "query" }, { "type": "boolean", "description": "append the id=0 no-assignee group without restricting results to unassigned tasks, available for /users only. The group accompanies every non-empty page (it is outside the user pagination), so paginating clients must dedupe it", "name": "include_unassigned", "in": "query" }, { "type": "boolean", "description": "include projected tasks from unmaterialized recurring periods; available for /users only; requires start_date and end_date", "name": "include_unmaterialized", "in": "query" }, { "type": "boolean", "description": "include the unified user and team assignees list on each task", "name": "include_assignees", "in": "query" }, { "type": "integer", "description": "filters tasks with a minimum number of days. based on start_date and end_date", "name": "min_days", "in": "query" }, { "type": "boolean", "description": "include tasks belonging to draft projects (default false hides them; requires view_draft_projects permission)", "name": "include_drafts", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "filter by the task's own custom field values. Repeatable; each entry is 'fieldID:value1,value2' (values within an entry are OR, separate entries AND). Trailing colon 'fieldID:' selects the no-value bucket (select/multi_select only).", "name": "cf_filter", "in": "query" }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "group_name", "-group_name" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "Tasks grouped by type", "schema": { "$ref": "#/definitions/taskgroup.taskGroupsResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Updates task groups and their entries' weights/parent group.\nOn the users dimension a move with an explicit null\ntarget_group_id lands the task in the no-assignee bucket\n(the id=0 group on reads); OMITTING the property on a move is\nrejected, so a forgotten field can never read as an unassign.\nThe bucket move enforces its invariant regardless of the source. The\ndates follow the move, direct user assignees and team\nassignments are cleared (a no-op for a task already inside the\nbucket, so repositions work the same way). The task takes the given weight\nin the bucket, which persists ordering like any other group.", "produces": [ "application/json" ], "tags": [ "task-groups" ], "summary": "Updates task groups and their entries' weights/parent group", "operationId": "update-task-groups", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "enum": [ "projects", "users", "tags" ], "type": "string", "description": "group type", "name": "group", "in": "path", "required": true }, { "description": "task groups to update with their entries", "name": "taskGroups", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/taskgroup.UpdateTaskGroupEntryParams" } } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/recurring": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of tasks based on the workspace ID.", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "List recurring task instances", "operationId": "list-tasks-recurring-instances", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "boolean", "description": "filter in/out archived tasks", "name": "archived", "in": "query" }, { "type": "string", "format": "date", "description": "filter tasks overlapping date range (start). Used with end_date to find tasks where task.start_date \u003c= end_date AND task.end_date \u003e= start_date", "name": "start_date", "in": "query" }, { "type": "string", "format": "date", "description": "filter tasks overlapping date range (end). Used with start_date to find tasks where task.start_date \u003c= end_date AND task.end_date \u003e= start_date", "name": "end_date", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use start_date instead", "name": "dates_overlap_start", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use end_date instead", "name": "dates_overlap_end", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by recurring task ids", "name": "recurring_task_ids", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter recurring task instances by team IDs", "name": "team_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter in recurring task instances assigned to these teams, without expanding the teams to their members", "name": "assignee_team_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter recurring task instances by assignee's user IDs", "name": "assignee_user_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter in tasks by tag IDs", "name": "tag_id", "in": "query" }, { "type": "boolean", "description": "includes the unified user and team assignees", "name": "include_assignees", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Page-models_Task" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/stream": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of tasks based on the workspace ID.", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "List tasks, streaming the response", "operationId": "list-stream-tasks", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "boolean", "description": "include time entries", "name": "with_entries", "in": "query" }, { "type": "boolean", "description": "filter by pinned state", "name": "pinned", "in": "query" }, { "type": "array", "items": { "enum": [ "user_id", "-user_id", "project_id", "-project_id", "parent_task_id", "-parent_task_id", "name", "-name", "estimated_mins", "-estimated_mins", "priority", "-priority", "priority_at", "-priority_at", "start_date", "-start_date", "end_date", "-end_date", "status_id", "-status_id", "pinned", "-pinned", "created_at", "-created_at", "updated_at", "-updated_at", "last_activity", "-last_activity", "position", "-position", "billable", "-billable", "relevance", "-relevance", "tag_ids", "-tag_ids", "assignees", "-assignees", "sub_tasks_grouped", "-sub_tasks_grouped" ], "type": "string" }, "collectionFormat": "csv", "description": "order by. tag_ids and assignees order by the canonicalized (sorted) array, so tasks with the same set of tags or assignees cluster together regardless of storage order. Also accepts pcf_\u003cid\u003e / -pcf_\u003cid\u003e to sort tasks by the named custom field on the task's parent project, and cf_\u003cid\u003e / -cf_\u003cid\u003e to sort by the task's own custom field. Multi_select and users CF types use the same canonicalized-array semantics. sub_tasks_grouped orders top-level tasks by name (direction applies) with each task's subtasks directly after it in position order; it cannot be combined with other order_by values.", "name": "order_by", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter in tasks by their status' ID", "name": "status_id", "in": "query" }, { "type": "integer", "description": "filter in tasks by user", "name": "toggl_user_id", "in": "query" }, { "type": "string", "description": "filter tasks by task name, project name, or client name", "name": "name", "in": "query" }, { "type": "boolean", "description": "when true, the name filter also matches the parent task's name, returning subtasks whose parent matches", "name": "include_parent_matches", "in": "query" }, { "type": "boolean", "description": "filter tasks if it has time entries", "name": "has_time_entries", "in": "query" }, { "type": "boolean", "description": "filter tasks if it has time blocks", "name": "has_time_blocks", "in": "query" }, { "type": "boolean", "description": "filter tasks by date presence: true returns tasks with start_date or end_date, false returns tasks with both dates NULL", "name": "has_dates", "in": "query" }, { "type": "boolean", "description": "filter tasks by private state", "name": "private", "in": "query" }, { "type": "boolean", "description": "filter in/out archived tasks", "name": "archived", "in": "query" }, { "type": "boolean", "description": "include tasks whose parent project is completed (default false hides them; tasks without a project are always returned)", "name": "include_project_completed", "in": "query" }, { "type": "boolean", "description": "include tasks belonging to draft projects (default false hides them; requires view_draft_projects permission; tasks without a project are always returned)", "name": "include_drafts", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by project ids. `?project_id=` will include tasks with no project.", "name": "project_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by parent task ids. `?parent_task_id=` will include tasks with no parent.", "name": "parent_task_id", "in": "query" }, { "type": "string", "format": "date", "description": "filter tasks overlapping date range (start). Used with end_date to find tasks where task.start_date \u003c= end_date AND task.end_date \u003e= start_date", "name": "start_date", "in": "query" }, { "type": "string", "format": "date", "description": "filter tasks overlapping date range (end). Used with start_date to find tasks where task.start_date \u003c= end_date AND task.end_date \u003e= start_date", "name": "end_date", "in": "query" }, { "type": "string", "format": "date", "description": "filter tasks active by a date (today_and_overdue preset): returns tasks that have at least one date and whose start_date is null or on or before the date; end_date is not upper-bounded so overdue tasks remain included", "name": "active_by_date", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use start_date instead", "name": "start_date_from", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use start_date instead", "name": "start_date_to", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use end_date instead", "name": "end_date_from", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use end_date instead", "name": "end_date_to", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use start_date instead", "name": "dates_overlap_start", "in": "query" }, { "type": "string", "format": "date", "description": "[LEGACY] use end_date instead", "name": "dates_overlap_end", "in": "query" }, { "type": "integer", "description": "filter by estimated mins min", "name": "estimated_mins_min", "in": "query" }, { "type": "integer", "description": "filter by estimated mins max", "name": "estimated_mins_max", "in": "query" }, { "type": "array", "items": { "enum": [ "plan", "focus", "google_calendar", "outlook_calendar" ], "type": "string" }, "collectionFormat": "csv", "description": "filter by sources", "name": "source", "in": "query" }, { "type": "array", "items": { "enum": [ "none", "low", "medium", "high" ], "type": "string" }, "collectionFormat": "csv", "description": "filter by priority", "name": "priority", "in": "query" }, { "type": "boolean", "description": "filter by whether task is a user priority", "name": "is_priority", "in": "query" }, { "type": "array", "items": { "enum": [ "timeblocked", "not_timeblocked", "tracked", "not_tracked", "active", "done" ], "type": "string" }, "collectionFormat": "csv", "description": "filter by state", "name": "state", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter in tasks by timeblock' IDs", "name": "time_block_id", "in": "query" }, { "type": "boolean", "description": "filter in/out tasks by completed timeblocks", "name": "time_block_completed", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter tasks by team IDs", "name": "team_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter in tasks assigned to these teams, without expanding the teams to their members", "name": "assignee_team_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter in tasks by assignee's user IDs", "name": "assignee_user_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter in tasks by tag IDs", "name": "tag_id", "in": "query" }, { "type": "boolean", "description": "filter by recurring tasks", "name": "recurring", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by recurring task ids", "name": "recurring_task_ids", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by client ids. `?client_id=` will include tasks with no client.", "name": "client_id", "in": "query" }, { "type": "boolean", "description": "includes the unified user and team assignees", "name": "include_assignees", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "filter by the task's own custom field values. Repeatable; each entry is 'fieldID:value1,value2' (values within an entry are OR, separate entries AND). Trailing colon 'fieldID:' selects the no-value bucket (select/multi_select only). Predicate vocabulary mirrors the project list cf_filter.", "name": "cf_filter", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/task.TaskWithParentAndAggregations" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a task by the provided ID.", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Get a task by ID", "operationId": "get-task", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "boolean", "description": "includes the unified user and team assignees", "name": "include_assignees", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/task.TaskWithParentAndAggregations" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "description": "Update an existing task", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Update task", "operationId": "update-task", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Task ID", "name": "task_id", "in": "path", "required": true }, { "description": "Task payload", "name": "task", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.UpdatePayload" } } ], "responses": { "204": { "description": "Task updated successfully" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes a task by the provided ID.", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Delete a task by ID", "operationId": "delete-task", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "format": "date", "description": "delete recurring tasks starting from this recurring task instance", "name": "from_recurring_task_id", "in": "query" }, { "type": "boolean", "description": "Conduct outbound sync or not", "name": "outbound_sync", "in": "query" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "description": "Partially update an existing task", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Partially update a task", "operationId": "patch-task", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Task ID", "name": "task_id", "in": "path", "required": true }, { "description": "Task payload", "name": "task", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.PartialUpdatePayload" } }, { "type": "integer", "description": "update recurring tasks starting from this recurring instance id", "name": "from_recurring_task_id", "in": "query" } ], "responses": { "204": { "description": "Task updated successfully" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/allocations": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the task's live estimate allocations. A task the user is not allowed to view yields an empty list.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "task-estimate-allocations" ], "summary": "List a task's estimate allocations", "operationId": "list-task-estimate-allocations", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.TaskEstimateAllocation" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates allocations for the task in bulk. All of a task's live allocations must share one value kind (allocated_mins or allocated_percent); the task's allocation_unit is a UI hint and is not enforced.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "task-estimate-allocations" ], "summary": "Create task estimate allocations", "operationId": "create-task-estimate-allocations", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "description": "allocations to create", "name": "body", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/taskestimateallocation.AllocationValues" } } } ], "responses": { "201": { "description": "Created allocations", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.TaskEstimateAllocation" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Task not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Allocation already exists for the entity", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Allocation unit mismatched, or entity not assigned", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Soft-deletes the task's allocations. Without the allocation ID(s), it deletes every live allocation of the task (resetting it to the even split); with it, deletes only the given allocations. Responds with the deleted allocations.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "task-estimate-allocations" ], "summary": "Delete task estimate allocations", "operationId": "delete-task-estimate-allocations", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "delete only these allocations (max 100); omit to delete all of the task's allocations", "name": "id", "in": "query" } ], "responses": { "200": { "description": "Deleted allocations", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.TaskEstimateAllocation" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Updates the task's allocations in bulk, matched by allocation ID. An allocation's task cannot change.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "task-estimate-allocations" ], "summary": "Update task estimate allocations", "operationId": "update-task-estimate-allocations", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "description": "allocations to update", "name": "body", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/taskestimateallocation.UpdatePayload" } } } ], "responses": { "200": { "description": "Updated allocations", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.TaskEstimateAllocation" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Allocation not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Allocation already exists for the entity", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Allocation unit mismatched, or entity not assigned", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/archive": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Archives a task, and all its time blocks \u0026 TEs with the provided task ID.", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Archive a task by ID", "operationId": "archive-task", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "format": "date", "description": "archive recurring tasks starting from this recurring task instance", "name": "from_recurring_task_id", "in": "query" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Task not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/attachments": { "get": { "description": "Returns a list of task-attachments based on the provided workspace ID, task ID and filter params.", "produces": [ "application/json" ], "tags": [ "task-attachments" ], "summary": "List task attachments", "operationId": "list-task-attachments", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "array", "items": { "enum": [ "created_at", "-created_at", "display_order", "-display_order" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.TaskAttachment" } } }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } }, "post": { "description": "Creates a new task attachment with the provided name and workspace ID.", "produces": [ "application/json" ], "tags": [ "task-attachments" ], "summary": "Create a new task attachment", "operationId": "create-task-attachment", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "string", "description": "Task attachment name", "name": "name", "in": "formData" }, { "type": "number", "description": "Task attachment display order", "name": "display_order", "in": "formData", "required": true }, { "type": "file", "description": "attachment file", "name": "file", "in": "formData", "required": true } ], "responses": { "201": { "description": "Task attachment created successfully", "schema": { "$ref": "#/definitions/models.TaskAttachment" } }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "404": { "description": "Task does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/attachments/bulk": { "post": { "description": "Creates up to 10 task attachments in a single request. All-or-nothing: if any file fails, none are created.", "produces": [ "application/json" ], "tags": [ "task-attachments" ], "summary": "Create task attachments in bulk", "operationId": "bulk-create-task-attachments", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "file" }, "collectionFormat": "csv", "description": "attachment files (max 10)", "name": "files", "in": "formData", "required": true }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "names for each file, indexed as names[0], names[1], etc.", "name": "names", "in": "formData" }, { "type": "array", "items": { "type": "number" }, "collectionFormat": "csv", "description": "display orders for each file, indexed as display_orders[0], display_orders[1], etc.", "name": "display_orders", "in": "formData", "required": true } ], "responses": { "201": { "description": "Task attachments created successfully", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.TaskAttachment" } } }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "404": { "description": "Task does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/attachments/{attachment_id}": { "put": { "description": "Update an existing task attachment", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "task-attachments" ], "summary": "Update task attachment", "operationId": "update-task-attachment", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "string", "description": "TaskAttachment ID", "name": "attachment_id", "in": "path", "required": true }, { "description": "TaskAttachment payload", "name": "taskAttachment", "in": "body", "required": true, "schema": { "$ref": "#/definitions/taskattachment.Payload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "404": { "description": "Task attachment does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } }, "delete": { "description": "Deletes a task attachment by the provided ID.", "produces": [ "application/json" ], "tags": [ "task-attachments" ], "summary": "Delete a task attachment by ID", "operationId": "delete-task-attachment", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "task attachment ID", "name": "attachment_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "404": { "description": "Task attachment does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/attachments/{attachment_id}/view": { "get": { "description": "View a task attachment by the provided ID.", "produces": [ "application/octet-stream", "image/png", "image/jpeg", "application/pdf" ], "tags": [ "task-attachments" ], "summary": "View a task attachment", "operationId": "view-task-attachment", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "task attachment ID", "name": "attachment_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.TaskAttachment" } }, "400": { "description": "Invalid request", "schema": { "type": "string" } }, "404": { "description": "TaskAttachment does not exist", "schema": { "type": "string" } }, "500": { "description": "Internal Server Error", "schema": { "type": "string" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/children": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a task and its children sub-tasks by the provided ID.", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Get a task with its children sub-tasks by ID", "operationId": "get-task-with-children", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "user_id", "-user_id", "project_id", "-project_id", "parent_task_id", "-parent_task_id", "name", "-name", "estimated_mins", "-estimated_mins", "priority", "-priority", "priority_at", "-priority_at", "start_date", "-start_date", "end_date", "-end_date", "status_id", "-status_id", "pinned", "-pinned", "created_at", "-created_at", "updated_at", "-updated_at", "last_activity", "-last_activity", "tag_ids", "-tag_ids", "assignees", "-assignees" ], "type": "string" }, "collectionFormat": "csv", "description": "order by. tag_ids and assignees order by the canonicalized (sorted) array, so tasks with the same set of tags or assignees cluster together regardless of storage order.", "name": "order_by", "in": "query" }, { "type": "integer", "description": "filter children tasks by status ID", "name": "status_id", "in": "query" }, { "type": "boolean", "description": "filter in/out archived tasks", "name": "archived", "in": "query" }, { "type": "array", "items": { "enum": [ "plan", "focus", "google_calendar", "outlook_calendar" ], "type": "string" }, "collectionFormat": "csv", "description": "filter by sources", "name": "source", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter children tasks by team IDs", "name": "team_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter in tasks by assignee's user IDs", "name": "assignee_user_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter in tasks by tag IDs", "name": "tag_id", "in": "query" }, { "type": "boolean", "description": "includes the unified user and team assignees", "name": "include_assignees", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Page-task_TaskWithParentAndAggregations" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/parents": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a task and its parent tasks by the provided ID.", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Get a task with its parent tasks by ID", "operationId": "get-task-with-parents", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "user_id", "-user_id", "project_id", "-project_id", "parent_task_id", "-parent_task_id", "name", "-name", "estimated_mins", "-estimated_mins", "priority", "-priority", "priority_at", "-priority_at", "start_date", "-start_date", "end_date", "-end_date", "status_id", "pinned", "-pinned", "-status_id", "created_at", "-created_at", "updated_at", "-updated_at", "last_activity", "-last_activity", "tag_ids", "-tag_ids", "assignees", "-assignees" ], "type": "string" }, "collectionFormat": "csv", "description": "order by. tag_ids and assignees order by the canonicalized (sorted) array, so tasks with the same set of tags or assignees cluster together regardless of storage order.", "name": "order_by", "in": "query" }, { "type": "integer", "description": "filter parent tasks by status ID", "name": "status_id", "in": "query" }, { "type": "boolean", "description": "filter in/out archived tasks", "name": "archived", "in": "query" }, { "type": "array", "items": { "enum": [ "plan", "focus", "google_calendar", "outlook_calendar" ], "type": "string" }, "collectionFormat": "csv", "description": "filter by sources", "name": "source", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter parent tasks by team IDs", "name": "team_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter in tasks by assignee's user IDs", "name": "assignee_user_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter in tasks by tag IDs", "name": "tag_id", "in": "query" }, { "type": "boolean", "description": "includes the unified user and team assignees", "name": "include_assignees", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Page-task_TaskWithParentAndAggregations" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/rates": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new rate for a given task.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "rates" ], "summary": "Create a task rate", "operationId": "create-task-rate", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "description": "Rate payload", "name": "rate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.CreateTaskRatePayload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/restore": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Restores a task by the provided ID.", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Restore a task by ID", "operationId": "restore-task", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Task not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/time-blocks": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of time blocks based on the provided workspace ID, task ID and filter params.", "produces": [ "application/json" ], "tags": [ "time-blocks" ], "summary": "List task time blocks", "operationId": "list-task-time-blocks-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "start", "-start", "task_id", "-task_id", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" }, { "type": "boolean", "description": "filter in/out archived time blocks", "name": "archived", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Page-timeblock_TimeBlockAggregate" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new time block with the provided name and workspace ID.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-blocks" ], "summary": "Create a new time block", "operationId": "create-time-block-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "description": "TimeBlock payload", "name": "timeBlock", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timeblock.Payload" } } ], "responses": { "201": { "description": "Time block created successfully", "schema": { "$ref": "#/definitions/models.TimeBlock" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/time-blocks/{time_block_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a time block by the provided ID.", "produces": [ "application/json" ], "tags": [ "time-blocks" ], "summary": "Get a time block by ID", "operationId": "get-time-block-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "timeBlock ID", "name": "time_block_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.TimeBlock" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "TimeBlock does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Update an existing time block", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-blocks" ], "summary": "Update time block", "operationId": "update-time-block-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "TimeBlock ID", "name": "time_block_id", "in": "path", "required": true }, { "description": "TimeBlock payload", "name": "timeBlock", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timeblock.Payload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time block does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes a time block by the provided ID.", "produces": [ "application/json" ], "tags": [ "time-blocks" ], "summary": "Delete a time block by ID", "operationId": "delete-time-block-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "time block ID", "name": "time_block_id", "in": "path", "required": true }, { "type": "boolean", "description": "Conduct outbound sync or not", "name": "outbound_sync", "in": "query" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time block does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Update an existing time block", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-blocks" ], "summary": "Update time block", "operationId": "partial-update-time-block-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "TimeBlock ID", "name": "time_block_id", "in": "path", "required": true }, { "description": "TimeBlock payload", "name": "timeBlock", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timeblock.PartialUpdatePayload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time block does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/time-blocks/{time_block_id}/archive": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Marks the time block with the provided WS, task, and time block IDs as archived", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-blocks" ], "summary": "Marks a time block as archived", "operationId": "archive-time-block-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "time block ID", "name": "time_block_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/time-blocks/{time_block_id}/restore": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Restores a time block by the provided ID.", "produces": [ "application/json" ], "tags": [ "time-blocks" ], "summary": "Restore a time block by ID", "operationId": "restore-time-block-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "time block ID", "name": "time_block_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time block does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/time-blocks/{time_block_id}/unarchive": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Marks the time block with the provided WS, task, and time block IDs as unarchived", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-blocks" ], "summary": "Marks a time block as unarchived", "operationId": "unarchive-time-block-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "time block ID", "name": "time_block_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/time-entries": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of time-entries based on the provided workspace ID, task ID and filter params.", "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "List task time entries", "operationId": "list-task-time-entries-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "start", "-start", "task_id", "-task_id", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" }, { "enum": [ "activity", "break" ], "type": "string", "description": "time entry type", "name": "type", "in": "query" }, { "type": "boolean", "description": "filter in/out archived TEs", "name": "archived", "in": "query" }, { "type": "integer", "description": "filter by timeblock id", "name": "time_block_id", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Page-models_TimeEntry" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new time entry in the specified workspace.\nAn optional `user_id` field can be provided to create a time entry on behalf of another user.\nWhen `user_id` differs from the authenticated user, the caller must have `manage_time_entries` permission.\nAn optional `project_id` overrides the task's project for this entry. When omitted, the entry inherits the task's project.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Create a new time entry", "operationId": "create-time-entry-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "description": "TimeEntry payload", "name": "timeEntry", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timeentry.CreatePayload" } } ], "responses": { "201": { "description": "Time entry created successfully", "schema": { "$ref": "#/definitions/models.TimeEntry" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Required field is missing (error=required_fields_missing) or is being cleared on a grandfathered entry (error=required_fields_deletion)", "schema": { "$ref": "#/definitions/timeentryconstraints.RequiredFieldsErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/time-entries/{time_entry_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a time entry by the provided ID.", "produces": [ "application/json" ], "tags": [ "time-entries-deprecated" ], "summary": "Get a time entry by ID", "operationId": "get-time-entry-with-task", "deprecated": true, "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "timeEntry ID", "name": "time_entry_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.TimeEntry" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "TimeEntry does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "description": "Update an existing time entry", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries-deprecated" ], "summary": "Update time entry", "operationId": "update-time-entry-with-task", "deprecated": true, "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "TimeEntry ID", "name": "time_entry_id", "in": "path", "required": true }, { "description": "TimeEntry payload", "name": "timeEntry", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timeentry.Payload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time entry does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Required field is missing (error=required_fields_missing) or is being cleared on a grandfathered entry (error=required_fields_deletion)", "schema": { "$ref": "#/definitions/timeentryconstraints.RequiredFieldsErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes a time entry by the provided ID.", "produces": [ "application/json" ], "tags": [ "time-entries-deprecated" ], "summary": "Delete a time entry by ID", "operationId": "delete-time-entry-with-task", "deprecated": true, "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "time entry ID", "name": "time_entry_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time entry does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "description": "Partial updates an existing time entry", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries-deprecated" ], "summary": "Partial update time entry", "operationId": "partial-update-time-entry-with-task", "deprecated": true, "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "TimeEntry ID", "name": "time_entry_id", "in": "path", "required": true }, { "description": "TimeEntry payload", "name": "timeEntry", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timeentry.PartialUpdatePayload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time entry does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Required field is missing (error=required_fields_missing) or is being cleared on a grandfathered entry (error=required_fields_deletion)", "schema": { "$ref": "#/definitions/timeentryconstraints.RequiredFieldsErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/time-entries/{time_entry_id}/archive": { "post": { "description": "Marks the TE with the provided WS, task, and TE IDs as archived", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries-deprecated" ], "summary": "Marks a TE as archived", "operationId": "archive-time-entry-with-task", "deprecated": true, "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "time entry ID", "name": "time_entry_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/time-entries/{time_entry_id}/restore": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Restores a time entry by the provided ID.", "produces": [ "application/json" ], "tags": [ "time-entries-deprecated" ], "summary": "Restore a time entry by ID", "operationId": "restore-time-entry-with-task", "deprecated": true, "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "time entry ID", "name": "time_entry_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time entry does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/time-entries/{time_entry_id}/unarchive": { "post": { "description": "Marks the TE with the provided WS, task, and TE IDs as unarchived", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries-deprecated" ], "summary": "Unarchives a time entry", "operationId": "unarchive-time-entry-with-task", "deprecated": true, "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true }, { "type": "integer", "description": "time entry ID", "name": "time_entry_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/{task_id}/unarchive": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Unarchives a task, and all its time blocks \u0026 TEs with the provided task ID.", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Unarchive a task by ID", "operationId": "unarchive-task", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "task ID", "name": "task_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Task not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/template-estimate-suggestions/{project_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "recurring-budget-suggestions" ], "summary": "Get template estimate suggestion", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Subject project ID (the template or a project created from it)", "name": "project_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/recurringbudget.suggestionResponse" } }, "204": { "description": "No suggestion to surface" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/template-estimate-suggestions/{project_id}/accept": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "tags": [ "recurring-budget-suggestions" ], "summary": "Accept a template estimate suggestion", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Subject project ID (the template or a project created from it)", "name": "project_id", "in": "path", "required": true } ], "responses": { "204": { "description": "Decision recorded" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "No current suggestion", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/template-estimate-suggestions/{project_id}/dismiss": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "tags": [ "recurring-budget-suggestions" ], "summary": "Dismiss a template estimate suggestion", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Subject project ID (the template or a project created from it)", "name": "project_id", "in": "path", "required": true } ], "responses": { "204": { "description": "Decision recorded" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "No current suggestion", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-blocks": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of time-blocks based on the provided workspace ID and filter params.", "produces": [ "application/json" ], "tags": [ "time-blocks" ], "summary": "List task time blocks within range", "operationId": "list-time-blocks-range-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "from timestamp", "name": "date_from", "in": "query", "required": true }, { "type": "string", "description": "to timestamp", "name": "date_to", "in": "query", "required": true }, { "type": "integer", "description": "task id", "name": "task_id", "in": "query" }, { "type": "integer", "description": "status id", "name": "status_id", "in": "query" }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "boolean", "description": "filter in/out archived time blocks", "name": "archived", "in": "query" }, { "type": "array", "items": { "enum": [ "start", "-start", "task_id", "-task_id", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Page-timeblock_TimeBlockAggregateWithTask" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-blocks/bulk": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates new time blocks", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-blocks" ], "summary": "Create new time blocks", "operationId": "bulk-create-time-block-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "TimeBlock payload", "name": "timeBlocks", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timeblock.BulkCreatePayload" } } ], "responses": { "201": { "description": "Time blocks created successfully", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.TimeBlock" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes time blocks by the provided IDs.", "produces": [ "application/json" ], "tags": [ "time-blocks" ], "summary": "Bulk deletes time blocks by IDs", "operationId": "bulk-delete-time-block-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "time block IDs", "name": "ids", "in": "query", "required": true }, { "type": "boolean", "description": "Conduct outbound sync or not", "name": "outbound_sync", "in": "query" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time block does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Update existing time blocks in bulk", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-blocks" ], "summary": "Update time blocks in bulk", "operationId": "bulk-partial-update-time-block-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "TimeBlock payload with ID", "name": "timeBlock", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/timeblock.PartialUpdatePayloadWithID" } } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time block does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-blocks/stream": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of time-blocks based on the provided workspace ID and filter params.", "produces": [ "application/json" ], "tags": [ "time-blocks" ], "summary": "List task time blocks within range (streamed)", "operationId": "list-time-blocks-range-stream-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "from timestamp", "name": "date_from", "in": "query", "required": true }, { "type": "string", "description": "to timestamp", "name": "date_to", "in": "query", "required": true }, { "type": "integer", "description": "task id", "name": "task_id", "in": "query" }, { "type": "integer", "description": "status id", "name": "status_id", "in": "query" }, { "type": "boolean", "description": "filter in/out archived time blocks", "name": "archived", "in": "query" }, { "type": "array", "items": { "enum": [ "start", "-start", "task_id", "-task_id", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/timeblock.TimeBlockAggregateWithTask" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-entries": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of time-entries based on the provided workspace ID and filter params.", "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "List task time entries", "operationId": "list-time-entries-range-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "from timestamp", "name": "date_from", "in": "query", "required": true }, { "type": "string", "description": "from timestamp", "name": "date_to", "in": "query", "required": true }, { "type": "integer", "description": "task id", "name": "task_id", "in": "query" }, { "type": "integer", "description": "status id", "name": "status_id", "in": "query" }, { "enum": [ "activity", "break" ], "type": "string", "description": "time entry type", "name": "type", "in": "query" }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "start", "-start", "task_id", "-task_id", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" }, { "type": "boolean", "description": "filter in/out archived TEs", "name": "archived", "in": "query" }, { "type": "integer", "description": "filter by timeblock", "name": "time_block_id", "in": "query" }, { "type": "boolean", "description": "include taskless time entries", "name": "include_taskless", "in": "query" }, { "type": "boolean", "description": "hydrate calendar event details inline", "name": "expand_calendar_event", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Page-timeentry_TimeEntryWithTask" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new time entry without a task for the specified workspace.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Create a taskless time entry", "operationId": "create-taskless-time-entry-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "TimeEntry payload", "name": "timeEntry", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timeentry.CreateTasklessPayload" } } ], "responses": { "201": { "description": "Time entry created successfully", "schema": { "$ref": "#/definitions/models.TimeEntry" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Required field is missing (error=required_fields_missing) or is being cleared on a grandfathered entry (error=required_fields_deletion)", "schema": { "$ref": "#/definitions/timeentryconstraints.RequiredFieldsErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-entries/batch": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the time entries matching the provided IDs, ordered by ID ascending.\nEach entry carries its tag override (tag_ids, null when the entry inherits from its\ntask) and the hydrated effective tags.\nDeleted time entries are silently omitted, so the response may be shorter than the\nrequested ID list.\nThe ID list is capped at the same 1000-id limit the bulk write endpoints accept, so any\nselection that can be bulk-edited can also be read in a single call.\nIDs may be sent either as repeated params (ids=1\u0026ids=2) or comma-separated (ids=1,2);\nboth are accepted, and the comma-separated form builds a request URL roughly 30%\nsmaller, which matters for large selections.\nCallers without the workspace-wide view permission (guests) are resolved per entry and\nthe whole request fails with 403 as soon as one requested entry is not accessible to\nthem — this includes entries whose task or project they cannot access, not only entries\nowned by someone else.", "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Get time entries by IDs", "operationId": "list-batch-time-entries-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "TimeEntry IDs, unique, up to the same 1000-id limit as the bulk write endpoints", "name": "ids", "in": "query", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.TimeEntry" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-entries/bulk": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates new time entries in bulk for the specified workspace.\nAn optional `user_id` field can be provided per entry to create time entries on behalf of another user.\nWhen `user_id` differs from the authenticated user, the caller must have `manage_time_entries` permission.\n`task_id` is optional; omitting it creates a taskless entry, optionally scoped to `project_id`.\nWhen both `task_id` and `project_id` are provided, `project_id` overrides the task's project for the entry.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Create new time entries in bulk", "operationId": "bulk-create-time-entry-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "TimeEntry payloads", "name": "timeEntry", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/timeentry.BulkCreatePayload" } } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "One or more time entries violate required-field constraints (error=bulk_required_fields_missing)", "schema": { "$ref": "#/definitions/timeentryconstraints.BulkRequiredFieldsErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes time entries by the provided IDs.", "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Delete time entries in bulk", "operationId": "bulk-delete-time-entry-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "TimeEntry IDs", "name": "ids", "in": "query", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time entry does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "description": "Partial updates an existing time entry", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Partial bulk update time entry", "operationId": "bulk-partial-update-time-entry-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "TimeEntry payloads with TE ID", "name": "timeEntries", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/timeentry.PartialUpdatePayloadWithID" } } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time entry does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "One or more time entries violate required-field constraints (error=bulk_required_fields_missing)", "schema": { "$ref": "#/definitions/timeentryconstraints.BulkRequiredFieldsErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-entries/bulk-edit": { "patch": { "description": "Applies a single set of field changes to every time entry listed in `ids`.\n`changes` uses partial-update semantics: fields omitted from the object are left\nunchanged, while an explicit null clears a nullable field. Editing entries the caller\ndoes not own requires the `manage_time_entries` permission.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Bulk edit time entries", "operationId": "bulk-edit-time-entries-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Target IDs and the changes to apply to all of them", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timeentry.BulkEditPayload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time entry does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "One or more time entries violate required-field constraints (error=bulk_required_fields_missing)", "schema": { "$ref": "#/definitions/timeentryconstraints.BulkRequiredFieldsErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-entries/bulk/restore": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Restores time entries by the provided IDs.", "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Restore time entries in bulk", "operationId": "bulk-restore-time-entry-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "TimeEntry IDs", "name": "ids", "in": "query", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time entry does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-entries/day-duration": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Reconciles time entries in a day to match the specified total duration.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Set day duration", "operationId": "set-day-duration-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Day duration payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timeentry.SetDayDurationPayload" } } ], "responses": { "200": { "description": "Reconciled time entries for the day", "schema": { "type": "array", "items": { "$ref": "#/definitions/timeentry.TimeEntryWithTask" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "One or more derived time entries violate required-field constraints (error=bulk_required_fields_missing)", "schema": { "$ref": "#/definitions/timeentryconstraints.BulkRequiredFieldsErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-entries/day-duration/bulk": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Atomically reconciles multiple (date_range, scope) pairs in one transaction.\nEach element of the array uses the same payload shape as the single endpoint.\nSame-day items within one batch apply sequentially.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Bulk set day duration", "operationId": "bulk-set-day-duration-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Day duration payloads", "name": "payload", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/timeentry.SetDayDurationPayload" } } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "One or more derived time entries violate required-field constraints (error=bulk_required_fields_missing)", "schema": { "$ref": "#/definitions/timeentryconstraints.BulkRequiredFieldsErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-entries/stream": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of time-entries based on the provided workspace ID and filter params.", "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "List task time entries, streaming the response", "operationId": "list-stream-time-entries-range-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "from timestamp", "name": "date_from", "in": "query", "required": true }, { "type": "string", "description": "from timestamp", "name": "date_to", "in": "query", "required": true }, { "type": "integer", "description": "task id", "name": "task_id", "in": "query" }, { "type": "integer", "description": "status id", "name": "status_id", "in": "query" }, { "enum": [ "activity", "break" ], "type": "string", "description": "time entry type", "name": "type", "in": "query" }, { "type": "array", "items": { "enum": [ "start", "-start", "task_id", "-task_id", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" }, { "type": "boolean", "description": "filter in/out archived TEs", "name": "archived", "in": "query" }, { "type": "boolean", "description": "include taskless time entries", "name": "include_taskless", "in": "query" }, { "type": "boolean", "description": "hydrate calendar event details inline", "name": "expand_calendar_event", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/timeentry.TimeEntryWithTask" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-entries/time-block-ids/stream": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of time-entries based on the provided workspace ID and filter params.", "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "List task time entries by time block ids, streaming the response", "operationId": "list-stream-time-entries-time-block-ids-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by timeblock ids", "name": "time_block_id", "in": "query", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.TimeEntry" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-entries/{time_entry_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a time entry by the provided ID.", "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Get a time entry by ID", "operationId": "get-time-entry-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "timeEntry ID", "name": "time_entry_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.TimeEntry" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "TimeEntry does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Update an existing time entry", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Update time entry", "operationId": "update-time-entry-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "TimeEntry ID", "name": "time_entry_id", "in": "path", "required": true }, { "description": "TimeEntry payload", "name": "timeEntry", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timeentry.Payload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time entry does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Required field is missing (error=required_fields_missing) or is being cleared on a grandfathered entry (error=required_fields_deletion)", "schema": { "$ref": "#/definitions/timeentryconstraints.RequiredFieldsErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Soft-deletes a time entry by the provided ID.", "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Delete a time entry by ID", "operationId": "delete-time-entry-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "time entry ID", "name": "time_entry_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time entry does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Partial updates an existing time entry", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Partial update time entry", "operationId": "partial-update-time-entry-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "TimeEntry ID", "name": "time_entry_id", "in": "path", "required": true }, { "description": "TimeEntry payload", "name": "timeEntry", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timeentry.PartialUpdatePayload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time entry does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Required field is missing (error=required_fields_missing) or is being cleared on a grandfathered entry (error=required_fields_deletion)", "schema": { "$ref": "#/definitions/timeentryconstraints.RequiredFieldsErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-entries/{time_entry_id}/archive": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Marks the time entry with the provided ID as archived", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Marks a TE as archived", "operationId": "archive-time-entry-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "time entry ID", "name": "time_entry_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-entries/{time_entry_id}/log": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Logs a planned entry's time in place — copies its planned start/duration onto the logged side — exactly once. Rejects with 409 if the entry is already logged. A calendar-linked entry that has no task or project is categorized via the user's active mapping rule, mirroring Create and Start tracking; when no rule matches, a best-effort suggestion from the user's time-log history is applied, matching how creating a logged entry from a calendar event is categorized.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Log a planned time entry", "operationId": "log-planned-time-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "time entry ID", "name": "time_entry_id", "in": "path", "required": true } ], "responses": { "200": { "description": "The logged time entry", "schema": { "$ref": "#/definitions/models.TimeEntry" } }, "400": { "description": "Invalid request (no planned time to log)", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Time entry has already been logged", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-entries/{time_entry_id}/restore": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Restores a time entry by the provided ID.", "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Restore a time entry by ID", "operationId": "restore-time-entry-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "time entry ID", "name": "time_entry_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Time entry does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-entries/{time_entry_id}/unarchive": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Marks the time entry with the provided ID as unarchived", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Unarchives a time entry", "operationId": "unarchive-time-entry-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "time entry ID", "name": "time_entry_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-log-suggestions": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-log-suggestions" ], "summary": "Get time-log suggestion for a calendar-event title", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Request body", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/tasksuggestion.timeLogSuggestionRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/tasksuggestion.timeLogSuggestionResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/time-log-suggestions/bulk": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-log-suggestions" ], "summary": "Get time-log suggestions for multiple calendar-event titles", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Request body", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/tasksuggestion.timeLogSuggestionBulkRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/tasksuggestion.timeLogSuggestionBulkItemResponse" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheet-setups": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the timesheet setups configured in the workspace — each one defines the period cadence, the approval chain and the members whose timesheets it generates. Setups whose end date has passed are left out unless `include_discontinued` is set, and the member and approver filters narrow the list to the setups a given user takes part in. Requires the `manage_timesheet_approvals` permission.", "produces": [ "application/json" ], "tags": [ "timesheet-setups" ], "summary": "List timesheet setups in the workspace", "operationId": "list-timesheet-setups", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "boolean", "description": "include setups whose end_date has passed", "name": "include_discontinued", "in": "query" }, { "type": "integer", "description": "filter to setups containing this member", "name": "user_account_id", "in": "query" }, { "type": "integer", "description": "filter to setups where this user is an approver", "name": "approver_user_account_id", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.TimesheetSetup" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "forbidden (requires manage_timesheet_approvals)", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "timesheet-setups" ], "summary": "Create a timesheet setup", "operationId": "create-timesheet-setup", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "setup configuration", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timesheetsetup.CreatePayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/models.TimesheetSetup" } }, "400": { "description": "validation failed", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "a member is already in another active setup", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheet-setups/{setup_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns one timesheet setup by ID, with its period cadence, start and end dates and reminder settings. The approval chain is available from the setup's `/approvers` endpoint. Requires the `manage_timesheet_approvals` permission.", "produces": [ "application/json" ], "tags": [ "timesheet-setups" ], "summary": "Get a timesheet setup", "operationId": "get-timesheet-setup", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.TimesheetSetup" } }, "403": { "description": "forbidden (requires manage_timesheet_approvals)", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "not found or deleted", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Periodicity, period_days, and start_date are immutable. All fields use patch semantics: omitted fields leave existing state alone. Send `reminder` to replace the reminder, `unset_reminder: true` to clear it; sending both returns 400.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "timesheet-setups" ], "summary": "Update a timesheet setup", "operationId": "update-timesheet-setup", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "description": "mutable fields", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timesheetsetup.UpdatePayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.TimesheetSetup" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "forbidden (requires manage_timesheet_approvals)", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "tags": [ "timesheet-setups" ], "summary": "Soft-delete a timesheet setup", "operationId": "delete-timesheet-setup", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "forbidden (requires manage_timesheet_approvals)", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheet-setups/{setup_id}/approvers": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the setup's active approvers ordered by layer, which is the chain a submitted timesheet travels through; several approvers may share one layer, in which case any of them can act for it. Requires the `manage_timesheet_approvals` permission.", "produces": [ "application/json" ], "tags": [ "timesheet-setups" ], "summary": "List active approvers of a timesheet setup", "operationId": "list-timesheet-setup-approvers", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.TimesheetSetupApprover" } } }, "400": { "description": "invalid setup ID", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "forbidden (requires manage_timesheet_approvals)", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "setup not found or deleted", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheet-setups/{setup_id}/discontinue": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Periods up to and including end_date continue to function; no new periods are generated past it. The setup remains visible in history. Use DELETE to soft-delete entirely.", "consumes": [ "application/json" ], "tags": [ "timesheet-setups" ], "summary": "Set the discontinuation date on a timesheet setup", "operationId": "discontinue-timesheet-setup", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "description": "end date", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timesheetsetup.DiscontinuePayload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "forbidden (requires manage_timesheet_approvals)", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheet-setups/{setup_id}/members": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the members assigned to a timesheet setup — the users whose timesheets it generates each period — with their current status. Members who have been discontinued are left out unless `include_discontinued` is set. Requires the `manage_timesheet_approvals` permission.", "produces": [ "application/json" ], "tags": [ "timesheet-setups" ], "summary": "List members of a timesheet setup", "operationId": "list-timesheet-setup-members", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "type": "boolean", "description": "include discontinued members", "name": "include_discontinued", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.TimesheetSetupMember" } } }, "400": { "description": "invalid setup ID", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "forbidden (requires manage_timesheet_approvals)", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "setup not found or deleted", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheet-setups/{setup_id}/members/{user_account_id}": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Single-row add: concurrent adds of different members don't clobber. Adding an already-active member returns 409; a discontinued member is reactivated; a previously deleted member gets a fresh enrolment. Enforces the one-active-setup-per-member rule.", "produces": [ "application/json" ], "tags": [ "timesheet-setups" ], "summary": "Add (or re-enrol) a single setup member", "operationId": "add-timesheet-setup-member", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "type": "integer", "description": "member user account ID", "name": "user_account_id", "in": "path", "required": true } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/models.TimesheetSetupMember" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "forbidden (requires manage_timesheet_approvals)", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "setup not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "member already active or overlaps another setup", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Removes the member from the setup and soft-deletes their timesheet records in the same transaction (recoverable, not a hard delete).", "tags": [ "timesheet-setups" ], "summary": "Delete a single setup member (\"Delete data\")", "operationId": "delete-timesheet-setup-member", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "type": "integer", "description": "member user account ID", "name": "user_account_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "setup or member not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheet-setups/{setup_id}/members/{user_account_id}/discontinue": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "The member keeps their past timesheets but accrues no new periods after end_date's period (or immediately when end_date is omitted). Reversible with reactivate.", "consumes": [ "application/json" ], "tags": [ "timesheet-setups" ], "summary": "Discontinue a single setup member", "operationId": "discontinue-timesheet-setup-member", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "type": "integer", "description": "member user account ID", "name": "user_account_id", "in": "path", "required": true }, { "description": "optional last-period end date", "name": "payload", "in": "body", "schema": { "$ref": "#/definitions/timesheetsetup.MemberDiscontinuePayload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "setup or member not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheet-setups/{setup_id}/members/{user_account_id}/reactivate": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Restores the member to active so new periods resume.", "tags": [ "timesheet-setups" ], "summary": "Reactivate a discontinued setup member", "operationId": "reactivate-timesheet-setup-member", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "type": "integer", "description": "member user account ID", "name": "user_account_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "setup or member not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheets": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the timesheets the caller may see whose period overlaps the required `date_from`/`date_to` window; a period is returned when it intersects the window at either edge, so the leading period is included even though it starts before `date_from`. The window may span at most 90 days (`date_to` no more than 90 days after `date_from`); a wider window is rejected with a 400 `list_window_too_large` error. Scope is every setup in the workspace for an admin with `manage_timesheet_approvals`, otherwise the setups the caller approves, or — for a member who approves nothing — their own; an explicit `setup_id` narrows to that one setup. Discontinued setups (`end_date` in the past) are excluded from this scope, but an explicit `setup_id` still resolves one, so retained history stays readable. Within a setup an admin or approver sees every member, a plain member only their own rows. Periods that have never been submitted are included as not-submitted rows; `statuses` narrows the result to the given approval states.", "produces": [ "application/json" ], "tags": [ "timesheets" ], "summary": "List timesheets visible to the caller", "operationId": "list-timesheets", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "filter to a single setup", "name": "setup_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter to members, comma-separated or repeated", "name": "user_account_ids", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter to setups staffed by these approvers, comma-separated or repeated", "name": "approver_user_account_ids", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter to members of these teams, comma-separated or repeated", "name": "team_ids", "in": "query" }, { "type": "integer", "description": "filter to timesheets whose current approval layer is staffed by this approver (their turn to act); combine with statuses=submitted for a pending-review view", "name": "current_layer_approver_user_account_id", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "filter to statuses, comma-separated or repeated (not_submitted, submitted, approved, changes_requested)", "name": "statuses", "in": "query" }, { "type": "string", "description": "inclusive start of the window; every period overlapping it is returned (YYYY-MM-DD)", "name": "date_from", "in": "query", "required": true }, { "type": "string", "description": "inclusive end of the window, at most 90 days after date_from; every period overlapping it is returned (YYYY-MM-DD)", "name": "date_to", "in": "query", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "page size", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/timesheet.Summary" } }, "headers": { "X-Period-From": { "type": "string", "description": "earliest matching period start (YYYY-MM-DD); absent when nothing matched" }, "X-Period-To": { "type": "string", "description": "latest matching period start (YYYY-MM-DD); absent when nothing matched" }, "X-Total-Count": { "type": "integer", "description": "rows matching the filters, before pagination" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheets/approvers": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the approvers staffing the timesheet setups visible to the caller, each with their account ID and display name. These are the values accepted by the `approver_user_account_ids` filter when listing timesheets.", "produces": [ "application/json" ], "tags": [ "timesheets" ], "summary": "List the approvers the caller can filter the approvals list by", "operationId": "list-timesheet-approvers", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/timesheet.ApproverRef" } } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheets/bulk/approve": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "timesheets" ], "summary": "Approve multiple timesheets under one setup", "operationId": "bulk-approve-timesheets", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "keys to approve", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timesheet.BulkApprovePayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/timesheet.BulkResult" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheets/bulk/request-changes": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "timesheets" ], "summary": "Request changes on multiple timesheets under one setup", "operationId": "bulk-request-changes-timesheets", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "keys and optional comment", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timesheet.BulkRequestChangesPayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/timesheet.BulkResult" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheets/bulk/withdraw": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "timesheets" ], "summary": "Withdraw multiple timesheets under one setup", "operationId": "bulk-withdraw-timesheets", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "keys to withdraw", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timesheet.BulkWithdrawPayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/timesheet.BulkResult" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheets/flags/{flag_id}": { "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "tags": [ "timesheets" ], "summary": "Remove a flag (its creator, or a manage_timesheet_approvals admin)", "operationId": "remove-timesheet-flag", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "flag ID", "name": "flag_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheets/{setup_id}/{start_date}/{user_account_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns everything needed to review one timesheet in a single call: the record and its parent setup, the ordered approval chain, the member it belongs to, the time entries whose start falls in the period (enriched with their task and project), the active flags on those entries, and the hours summary. Visible to the member, to any approver in the setup's chain, and to workspace admins with `manage_timesheet_approvals`.", "produces": [ "application/json" ], "tags": [ "timesheets" ], "summary": "Get the full detail view of a timesheet", "operationId": "get-timesheet-details", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "type": "string", "description": "period start (YYYY-MM-DD)", "name": "start_date", "in": "path", "required": true }, { "type": "integer", "description": "member user account ID", "name": "user_account_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/timesheet.Details" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheets/{setup_id}/{start_date}/{user_account_id}/approve": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "timesheets" ], "summary": "Approve a timesheet (approver at the current layer, or a manage_timesheet_approvals admin override)", "operationId": "approve-timesheet", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "type": "string", "description": "period start (YYYY-MM-DD)", "name": "start_date", "in": "path", "required": true }, { "type": "integer", "description": "member user account ID", "name": "user_account_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.Timesheet" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheets/{setup_id}/{start_date}/{user_account_id}/flags": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the active flags on a timesheet — the individual time entries an approver marked as needing attention, each with the flagging approver and their comment. Flags clear when the member resubmits, when the timesheet is approved, or when the flagged entry is deleted, so an empty list means nothing is currently disputed.", "produces": [ "application/json" ], "tags": [ "timesheets" ], "summary": "List the active flags on a timesheet", "operationId": "list-timesheet-flags", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "type": "string", "description": "period start (YYYY-MM-DD)", "name": "start_date", "in": "path", "required": true }, { "type": "integer", "description": "member user account ID", "name": "user_account_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.TimesheetFlag" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "timesheets" ], "summary": "Flag a time entry within a timesheet period", "operationId": "add-timesheet-flag", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "type": "string", "description": "period start (YYYY-MM-DD)", "name": "start_date", "in": "path", "required": true }, { "type": "integer", "description": "member user account ID", "name": "user_account_id", "in": "path", "required": true }, { "description": "time entry and comment", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timesheet.AddFlagPayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/models.TimesheetFlag" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheets/{setup_id}/{start_date}/{user_account_id}/history": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the review trail of a timesheet in chronological order — every submission, withdrawal, approval and change request — with the acting user, any comment left, and when it happened. Empty for a period that has never been submitted.", "produces": [ "application/json" ], "tags": [ "timesheets" ], "summary": "Get the review audit trail of a timesheet", "operationId": "get-timesheet-history", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "type": "string", "description": "period start (YYYY-MM-DD)", "name": "start_date", "in": "path", "required": true }, { "type": "integer", "description": "member user account ID", "name": "user_account_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.TimesheetReview" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheets/{setup_id}/{start_date}/{user_account_id}/hours": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the time totals for a timesheet's period: logged, billable (with its share of the total), planned, and the member's expected working capacity. Only entries whose start falls in the period, in the member's timezone, are counted — an entry that overlaps the boundary belongs to the period it starts in.", "produces": [ "application/json" ], "tags": [ "timesheets" ], "summary": "Get the hours summary for a timesheet period", "operationId": "get-timesheet-hours", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "type": "string", "description": "period start (YYYY-MM-DD)", "name": "start_date", "in": "path", "required": true }, { "type": "integer", "description": "member user account ID", "name": "user_account_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/timesheet.HoursSummary" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheets/{setup_id}/{start_date}/{user_account_id}/request-changes": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "timesheets" ], "summary": "Send a timesheet back to the member with an optional comment", "operationId": "request-changes-timesheet", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "type": "string", "description": "period start (YYYY-MM-DD)", "name": "start_date", "in": "path", "required": true }, { "type": "integer", "description": "member user account ID", "name": "user_account_id", "in": "path", "required": true }, { "description": "comment (optional)", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timesheet.CommentPayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.Timesheet" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheets/{setup_id}/{start_date}/{user_account_id}/resubmit": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "timesheets" ], "summary": "Resubmit a timesheet after changes were requested", "operationId": "resubmit-timesheet", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "type": "string", "description": "period start (YYYY-MM-DD)", "name": "start_date", "in": "path", "required": true }, { "type": "integer", "description": "member user account ID", "name": "user_account_id", "in": "path", "required": true }, { "description": "optional comment", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timesheet.CommentPayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.Timesheet" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheets/{setup_id}/{start_date}/{user_account_id}/submit": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "timesheets" ], "summary": "Submit a timesheet for approval", "operationId": "submit-timesheet", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "type": "string", "description": "period start (YYYY-MM-DD)", "name": "start_date", "in": "path", "required": true }, { "type": "integer", "description": "member user account ID", "name": "user_account_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.Timesheet" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/timesheets/{setup_id}/{start_date}/{user_account_id}/withdraw": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "timesheets" ], "summary": "Withdraw a submitted timesheet or a prior approval", "operationId": "withdraw-timesheet", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "setup ID", "name": "setup_id", "in": "path", "required": true }, { "type": "string", "description": "period start (YYYY-MM-DD)", "name": "start_date", "in": "path", "required": true }, { "type": "integer", "description": "member user account ID", "name": "user_account_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.Timesheet" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tracking/current": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Get current tracked time entry.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tracking" ], "summary": "Get current tracked time entry", "operationId": "get-tracked-time-entry-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Time entry", "schema": { "$ref": "#/definitions/models.TimeEntry" } }, "204": { "description": "Not tracking a time entry" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tracking/start": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Start tracking time entry. If a running entry already exists it is automatically stopped and the new entry is returned.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tracking" ], "summary": "Start tracking time entry", "operationId": "start-tracking-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timeentry.StartTrackingPayload" } } ], "responses": { "200": { "description": "Time entry", "schema": { "$ref": "#/definitions/models.TimeEntry" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "User task does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Required field is missing (error=required_fields_missing) or is being cleared on a grandfathered entry (error=required_fields_deletion)", "schema": { "$ref": "#/definitions/timeentryconstraints.RequiredFieldsErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tracking/start-from-description": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Resolves or creates a task from descriptive metadata (name, project, tags), then starts tracking on it.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tracking" ], "summary": "Start tracking from description", "operationId": "start-tracking-from-description-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/extensiontracking.StartFromDescriptionPayload" } } ], "responses": { "200": { "description": "Tracking started", "schema": { "$ref": "#/definitions/extensiontracking.StartFromDescriptionResult" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Cannot track multiple time entries at the same time", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tracking/stop": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Stop tracking time entry.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tracking" ], "summary": "Stop tracking time entry", "operationId": "stop-tracking-with-org", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "payload", "name": "payload", "in": "body", "schema": { "$ref": "#/definitions/timeentry.StopTrackingPayload" } } ], "responses": { "200": { "description": "Time entry", "schema": { "$ref": "#/definitions/models.TimeEntry" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not tracking a time entry", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Required field is missing (error=required_fields_missing) or is being cleared on a grandfathered entry (error=required_fields_deletion)", "schema": { "$ref": "#/definitions/timeentryconstraints.RequiredFieldsErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/universal-importer/profiles": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the active import profiles saved for this workspace, newest first. Active profiles are capped per workspace.", "produces": [ "application/json" ], "tags": [ "csv-importer" ], "summary": "List reusable CSV import profiles", "operationId": "csv-list-profiles", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/csv.ListProfilesResponse" } }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Persists a workspace-scoped mapping for reuse. Capped per workspace — exceeding the cap returns 409 with code `profile_limit_reached`.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "csv-importer" ], "summary": "Create a CSV import profile", "operationId": "csv-create-profile", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Profile to create", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/csv.CreateProfileRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/csv.ProfileResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Name conflict or profile limit reached", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/universal-importer/profiles/from-file": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Convenience endpoint — pulls the file's already-saved column_mappings + metadata and persists them as a profile.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "csv-importer" ], "summary": "Save the current file mapping as a reusable profile", "operationId": "csv-create-profile-from-file", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Source file + profile metadata", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/csv.CreateProfileFromFileRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/csv.ProfileResponse" } }, "400": { "description": "Invalid request (file has no mapping yet)", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "File not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Name conflict or profile limit reached", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/universal-importer/profiles/{profile_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "csv-importer" ], "summary": "Get a single CSV import profile", "operationId": "csv-get-profile", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "profile ID", "name": "profile_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/csv.ProfileResponse" } }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Profile not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Applies partial changes — only the fields present in the request are touched.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "csv-importer" ], "summary": "Update a CSV import profile", "operationId": "csv-update-profile", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "profile ID", "name": "profile_id", "in": "path", "required": true }, { "description": "Fields to update", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/csv.UpdateProfileRequest" } } ], "responses": { "200": { "description": "Updated", "schema": { "$ref": "#/definitions/csv.ProfileResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Profile not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Name conflict", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "tags": [ "csv-importer" ], "summary": "Soft-delete a CSV import profile", "operationId": "csv-delete-profile", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "profile ID", "name": "profile_id", "in": "path", "required": true } ], "responses": { "204": { "description": "Deleted" }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Profile not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/universal-importer/upload": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new upload import request and attaches 1–10 CSV files (max 10 MB each). Returns the job ID, parsed file metadata (headers, sample rows, detected delimiter), and the registry of available target entity schemas for subsequent mapping.", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "csv-importer" ], "summary": "Create a universal CSV import request", "operationId": "csv-upload", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "file" }, "collectionFormat": "csv", "description": "CSV files (1–10, max 10 MB each)", "name": "file", "in": "formData", "required": true } ], "responses": { "201": { "description": "Upload request created", "schema": { "$ref": "#/definitions/csv.UploadResponse" } }, "400": { "description": "Invalid request (no files, too many files, file too large, invalid encoding, invalid file type, empty file)", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "An import is already in progress for this workspace", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/universal-importer/uploads": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a paginated list of upload import requests for the given workspace, each with their attached files.", "produces": [ "application/json" ], "tags": [ "csv-importer" ], "summary": "List upload import requests for a workspace", "operationId": "csv-list-upload-requests", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.PageWithTotal-csv_UploadRequestResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/universal-importer/uploads/{request_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a single upload import request with its attached files, current mapping (if any), stats, and warnings. Per entity type the stats break down as total = created + updated + matched + skipped + failed, where updated counts rows that matched an existing entity the import then wrote to (see csv.EntityStats) and matched counts the ones it found and left alone.", "produces": [ "application/json" ], "tags": [ "csv-importer" ], "summary": "Get an upload import request", "operationId": "csv-get-upload-request", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "upload import request ID", "name": "request_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/csv.UploadRequestResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Upload import request not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Soft-deletes the upload request and its files, freeing the per-workspace active-upload lock so a new POST /upload can succeed. Allowed only while the request is in pending, mapping, or ready — running imports (importing/reverting) and terminal statuses return 409. A repeat DELETE on an already-canceled request returns 404 (the FE should treat 404 as success).", "tags": [ "csv-importer" ], "summary": "Cancel a non-terminal CSV upload request", "operationId": "csv-cancel-upload", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "upload import request ID", "name": "request_id", "in": "path", "required": true } ], "responses": { "204": { "description": "Canceled" }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Upload import request not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Request cannot be canceled in its current status", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/universal-importer/{request_id}/confirm": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Starts the asynchronous Cadence workflow that parses CSV files into NDJSON and imports entities tier-by-tier (custom field definitions, clients, projects, tags, users, tasks, time entries). The upload must be in \"mapping\" status, or already \"importing\" for idempotent retries. Uses a deterministic workflow ID so retries are safe. Poll GET /uploads/{request_id} for progress and final status. In every mode, a user the managers column names who is already a plain member of that project is promoted to project manager, and nobody is ever demoted — so re-running an import can change existing people's roles, and revert does not undo it. Set match_existing_only=true to import in match-only mode: clients, projects, tasks, and users are matched against existing rows and never created — unmatched clients/projects/tasks and unmatched users (never invited) are skipped, along with the time entries depending on them; custom field definitions are neither created nor extended in this mode, so every field-catalog row is skipped. A matched project is still updated from its row (custom field values merged, tags linked, members/managers granted, billable set when the cell has a value), and so is a matched task (custom field values merged, tags linked, assignees added, and description/estimated_minutes/start_date/end_date/billable set when the cell has a value — archived is create-only, since archiving has to cascade to subtasks and time entries); those updates are not undone by revert. A project match covers archived, completed and inactive projects but never a recurring template, and a name+client several live projects share (recurring instances, for example) is skipped with a warning rather than written to whichever one the database returned first. A task match is refused the same way: a name several live tasks share under the same project and parent is skipped, and so is a task belonging to a recurring series, whose every future instance would otherwise inherit the row's values. A project or task the import wrote to is reported under stats.projects.updated / stats.tasks.updated rather than matched, so the summary separates the rows that changed from the ones that were only found.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "csv-importer" ], "summary": "Confirm and start the CSV import", "operationId": "csv-confirm-import", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "upload import request ID", "name": "request_id", "in": "path", "required": true }, { "description": "Optional confirm options (empty body accepted)", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/csv.ConfirmRequest" } } ], "responses": { "202": { "description": "Import workflow accepted", "schema": { "$ref": "#/definitions/csv.UploadWorkflowAck" } }, "400": { "description": "Invalid request (bad JSON)", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Upload import request not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Request is not in a confirmable state", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/universal-importer/{request_id}/dry-run": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Starts an asynchronous Cadence workflow that computes an accurate created/skipped/failed diff against the current DB state without writing anything, so an admin can review exactly what would be created vs matched before confirming. The upload must be in \"mapping\" or \"ready\" status. Mutually exclusive with a real import: the dry-run is rejected if an import is running, and a confirm is rejected while a dry-run is running. Poll GET /uploads/{request_id} for dry_run_status, dry_run_progress, and dry_run_result. Set match_existing_only=true to preview a match-only import (unmatched clients/projects/tasks/users reported as would-be-skipped rather than would-create; users are never invited; every field-catalog row is reported as would-be-skipped, since custom field definitions are neither created nor extended in that mode; a matched project's or task's own row values are validated so bad custom field values, billable cells and unreadable task dates/estimates surface as warnings, and a row carrying values to write is previewed under counts.projects.updated / counts.tasks.updated with row status \"updated\"; a project name+client that several live projects share is reported as would-be-skipped, and so is a task name several live tasks share under the same project and parent or one belonging to a recurring series).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "csv-importer" ], "summary": "Start a read-only dry-run of the CSV import", "operationId": "csv-dry-run", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "upload import request ID", "name": "request_id", "in": "path", "required": true }, { "description": "Optional dry-run options (empty body accepted)", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/csv.DryRunRequest" } } ], "responses": { "202": { "description": "Dry-run workflow accepted", "schema": { "$ref": "#/definitions/csv.UploadWorkflowAck" } }, "400": { "description": "Invalid request (bad JSON)", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Upload import request not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Request is not in a dry-runnable state, or a dry-run/import is already in progress", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/universal-importer/{request_id}/files": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Appends a single CSV file (max 10 MB) to a pending upload import request. Returns the updated upload request with all attached files.", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "csv-importer" ], "summary": "Add a file to an existing upload import request", "operationId": "csv-add-file", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "upload import request ID", "name": "request_id", "in": "path", "required": true }, { "type": "file", "description": "CSV file (max 10 MB)", "name": "file", "in": "formData", "required": true } ], "responses": { "200": { "description": "File added", "schema": { "$ref": "#/definitions/csv.UploadResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Upload import request not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Request is not in a pending state", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/universal-importer/{request_id}/files/{file_id}": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Replaces the contents of an existing file on a pending upload import request. Any previously submitted mapping for the file is cleared.", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "csv-importer" ], "summary": "Replace a file on an upload import request", "operationId": "csv-replace-file", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "upload import request ID", "name": "request_id", "in": "path", "required": true }, { "type": "integer", "description": "file ID to replace", "name": "file_id", "in": "path", "required": true }, { "type": "file", "description": "CSV file (max 10 MB)", "name": "file", "in": "formData", "required": true } ], "responses": { "200": { "description": "File replaced", "schema": { "$ref": "#/definitions/csv.UploadResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Upload import request or file not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Request is not in a pending state", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Soft-deletes a file from a pending upload import request.", "tags": [ "csv-importer" ], "summary": "Remove a file from an upload import request", "operationId": "csv-remove-file", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "upload import request ID", "name": "request_id", "in": "path", "required": true }, { "type": "integer", "description": "file ID to remove", "name": "file_id", "in": "path", "required": true } ], "responses": { "204": { "description": "File removed" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Upload import request or file not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Request is not in a pending state", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/universal-importer/{request_id}/mapping": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Validates the user-supplied per-file column mappings, normalizes a full scan of each file, deduplicates entities by key, and returns preview entity counts plus any validation warnings (row/column/field level). The returned unmapped_columns map lists source headers that are not bound to any target field.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "csv-importer" ], "summary": "Submit column mappings for an upload import request", "operationId": "csv-put-mapping", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "upload import request ID", "name": "request_id", "in": "path", "required": true }, { "description": "Per-file column mappings", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/csv.MappingRequest" } } ], "responses": { "200": { "description": "Mapping accepted; preview counts and warnings returned", "schema": { "$ref": "#/definitions/csv.MappingResponse" } }, "400": { "description": "Invalid mapping (missing required fields, unknown entity, conflicting source_column and literal, etc.)", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Upload import request not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Request is not mappable or its file set has changed since the mapping was prepared", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/universal-importer/{request_id}/revert": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Starts an asynchronous Cadence workflow that soft-deletes every entity recorded for this upload, in reverse-tier order (time entries → tasks → tags → projects → clients). The workflow is best-effort: per-entity delete failures are recorded as warnings while the run terminates as \"reverted\". Allowed source statuses: completed, completed_with_errors. Calling against an upload already in \"reverting\" is treated as an idempotent no-op (Cadence dedupes via the deterministic workflow ID). This removes only rows the import created, so writes it made to pre-existing rows survive the revert: the custom field values, tags, memberships, manager promotions and billable flag applied to a matched project (stats.projects.updated counts them), the custom field values, tags, assignees and description/estimated_minutes/start_date/end_date/billable applied to a matched task (stats.tasks.updated counts them), and the select options added to a matched custom field. Imported users are not deleted in this version, and neither are custom field definitions the import created — the run warns with their count so an admin can remove them from workspace settings. Poll GET /uploads/{request_id} for progress and final status.", "produces": [ "application/json" ], "tags": [ "csv-importer" ], "summary": "Revert a completed CSV import", "operationId": "csv-revert-import", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "upload import request ID", "name": "request_id", "in": "path", "required": true } ], "responses": { "202": { "description": "Revert workflow accepted", "schema": { "$ref": "#/definitions/csv.UploadWorkflowAck" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Universal CSV importer beta feature is not enabled for the user, or the caller is not a workspace admin (beta gate also acts as a kill switch for ongoing reverts during launch rollback)", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Upload import request not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Request is not in a revertable state", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/users/me/goals": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns all active and inactive goals owned by the authenticated user in the workspace.", "produces": [ "application/json" ], "tags": [ "goals" ], "summary": "List goals", "operationId": "list-goals", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Goals", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Goal" } } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/users/me/onboarding-answers": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the current onboarding answers for the authenticated user in the workspace. Returns an empty default if no record exists.", "produces": [ "application/json" ], "tags": [ "onboarding-answers" ], "summary": "Get onboarding answers", "operationId": "get-onboarding-answers", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Onboarding answers retrieved successfully", "schema": { "$ref": "#/definitions/models.OnboardingAnswers" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates or updates onboarding answers with merge semantics. If no record exists, one is created. On subsequent calls, provided fields are merged into the existing record. Omitted fields are unchanged. Setting an answer to null clears it. Setting completed to true sets completed_at.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "onboarding-answers" ], "summary": "Upsert onboarding answers", "operationId": "partial-update-onboarding-answers", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Partial update payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/onboardinganswers.PartialUpdatePayload" } } ], "responses": { "200": { "description": "Successfully updated", "schema": { "$ref": "#/definitions/models.OnboardingAnswers" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/users/{user_id}/custom-field-values": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Applies merge-patch semantics to the custom-field values stored about a workspace member: keys in `custom_fields` override stored values, explicit nulls delete individual fields, unmentioned keys are preserved, and a JSON-null `custom_fields` clears all values. The subject must be a current member of the workspace.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "custom-fields" ], "summary": "Patch a member's custom field values", "operationId": "patch-user-custom-field-values", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "toggl user ID of the member whose values are written", "name": "user_id", "in": "path", "required": true }, { "description": "Merge patch", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/usercustomfield.PatchValuesPayload" } } ], "responses": { "200": { "description": "Merged values", "schema": { "$ref": "#/definitions/usercustomfield.ValuesResponse" } }, "400": { "description": "Invalid body, invalid values, or subject is not a workspace member", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "user_custom_fields feature not available on the plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Missing update_user_custom_fields permission or beta not enabled", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/workflows/tasks/extract": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Parses the provided image and returns a list of tasks.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Parse image and retrieve tasks", "operationId": "extract-tasks-form-image", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "file", "description": "attachment file", "name": "file", "in": "formData", "required": true } ], "responses": { "200": { "description": "Image parsed successfully", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Task" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } }, "503": { "description": "Task generation failed", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/workflows/tasks/from-list": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Parses the provided text list and returns a list of tasks.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Parse text list and retrieve tasks", "operationId": "extract-tasks-from-list", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Prompt payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.PromptPayload" } } ], "responses": { "200": { "description": "List parsed successfully", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Task" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } }, "503": { "description": "Task generation failed", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/workflows/tasks/prompt": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Generates tasks from prompt", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Generates tasks from prompt", "operationId": "generate-tasks-from-prompt", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Prompt payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/task.PromptPayload" } } ], "responses": { "200": { "description": "Prompt parsed successfully", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Task" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } }, "503": { "description": "Task generation failed", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/reports/workspaces/{workspace_id}/profitability": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns profitability actuals (revenue, labor cost) from the analytics warehouse plus", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "reports" ], "summary": "Generate profitability report with forecast", "operationId": "get-profitability-report", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "enum": [ "json_row", "hierarchical" ], "type": "string", "description": "response data format", "name": "response_format", "in": "query" }, { "type": "boolean", "default": false, "description": "include dictionary data in response", "name": "include_dicts", "in": "query" }, { "enum": [ "csv", "xlsx", "pdf" ], "type": "string", "description": "Export mode. Each mode requires its own entitlement: 'csv' → report_export_csv, 'xlsx' → report_export_xlsx, 'pdf' → report_export_pdf. All three gate the paid export feature while the JSON body is unchanged — the file itself is built by the FE exports service.", "name": "X-Toggl-Report-Export", "in": "header" }, { "description": "Query with period, optional filters and optional date grouping", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.QueryRequest" } } ], "responses": { "200": { "description": "Report rows with forecast_revenue and forecast_labor_cost injected", "schema": { "$ref": "#/definitions/flexq.EnrichedResult" } }, "400": { "description": "Invalid request or unsupported grouping", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "FX rate missing for the target currency (fx_rate_missing)", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/reports/workspaces/{workspace_id}/query": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Executes a flexible query against the analytics database and returns formatted results.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "reports" ], "summary": "Generate flexible query report", "operationId": "get-flexq-data", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "enum": [ "json_row", "table", "hierarchical" ], "type": "string", "description": "response data format", "name": "response_format", "in": "query" }, { "type": "boolean", "default": false, "description": "include dictionary data in response", "name": "include_dicts", "in": "query" }, { "enum": [ "csv", "xlsx", "pdf" ], "type": "string", "description": "Export mode. Each mode requires its own entitlement: 'csv' → report_export_csv, 'xlsx' → report_export_xlsx, 'pdf' → report_export_pdf. All three gate the paid export feature while the JSON body is unchanged — the file itself is built by the FE exports service.", "name": "X-Toggl-Report-Export", "in": "header" }, { "description": "Query configuration including filters, aggregations, groupings, etc.", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.QueryRequest" } } ], "responses": { "200": { "description": "Report as JSON", "schema": { "$ref": "#/definitions/flexq.EnrichedResult" } }, "400": { "description": "Invalid request parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Report view quota exceeded", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden — the plan lacks the report export entitlement", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Currency conversion requested but an FX rate is missing for the period", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/reports/workspaces/{workspace_id}/query/dictionary": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Generates a dictionary containing task, project, client, and status information based on the provided filters.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "reports" ], "summary": "Generate dictionary from filters", "operationId": "get-flexq-dictionary", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Filter criteria for dictionary generation", "name": "request", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/dto.FilterRequest" } } } ], "responses": { "200": { "description": "Successfully generated dictionary", "schema": { "$ref": "#/definitions/dictionary.Dictionary" } }, "400": { "description": "Invalid request parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/reports/workspaces/{workspace_id}/workload": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Generates a workload report based on the given input.\nBreakdown reports (grouped by user_account_id) support optional pagination via 'page' and 'per_page'.\nPaginated response includes 'total_count' with the total number of users matching the filters.\nAn ordination on 'user_account_id' ('asc' or 'desc') orders breakdown members by display name across the whole result, not just the current page; it defaults to ascending. Ordinations on other properties are passed through to the reporting engine.\nTotals rows, trend buckets, and breakdown nodes include working, scheduled, scheduled draft, and scheduled remaining sums in minutes.\nThe fields are 'sum_working_minutes', 'sum_scheduled_minutes', 'sum_scheduled_draft_minutes', and 'sum_scheduled_remaining_minutes'.\nScheduled minutes cover non-draft task estimates, projected unmaterialized recurring periods, and planned calendar events.\nScheduled draft minutes are gross task estimates from visible draft projects. Zero means none or not visible.\nA draft legacy calendar task can overlap with its still-planned calendar event, so the draft and scheduled sums are not strictly additive.\nScheduled remaining minutes net each assignee's tracked time and roll unfinished estimates forward from workspace-local today.\nPast and overdue task slices are zero, while planned events count only from today.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "reports" ], "summary": "Generate workload report", "operationId": "get-workload-report", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "enum": [ "csv", "xlsx", "pdf" ], "type": "string", "description": "Export mode. Each mode requires its own entitlement: 'csv' → report_export_csv, 'xlsx' → report_export_xlsx, 'pdf' → report_export_pdf. All three gate the paid export feature while the JSON body is unchanged — the file itself is built by the FE exports service.", "name": "X-Toggl-Report-Export", "in": "header" }, { "description": "Query configuration with optional filters and groupings", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.QueryRequest" } } ], "responses": { "200": { "description": "Successfully generated workload report", "schema": { "$ref": "#/definitions/flexq.EnrichedResult" } }, "400": { "description": "Invalid request parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/users/me/settings": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "user-settings" ], "summary": "Retrieve user settings", "operationId": "get-user-settings", "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.UserSettings" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Partial update user settings.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "user-settings" ], "summary": "Partial update user settings", "operationId": "partial-update-user-settings", "parameters": [ { "description": "Settings payload", "name": "settings", "in": "body", "required": true, "schema": { "$ref": "#/definitions/user.PartialUpdatePayload" } } ], "responses": { "200": { "description": "Successfully updated", "schema": { "$ref": "#/definitions/models.UserSettings" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/version": { "get": { "description": "Returns the running service version (semver tag or git revision).", "produces": [ "application/json" ], "tags": [ "version" ], "summary": "Service version", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/api.VersionResponse" } } } } }, "/workspaces/{workspace_id}/clients": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of clients based on the provided workspace ID and filter params.", "produces": [ "application/json" ], "tags": [ "clients" ], "summary": "List clients", "operationId": "list-clients", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "name", "-name", "active", "-active", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" }, { "type": "string", "description": "filter clients by their names", "name": "name", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Page-models_Client" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new client with the provided name and workspace ID.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "clients" ], "summary": "Create a new client", "operationId": "create-client", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Client payload", "name": "client", "in": "body", "required": true, "schema": { "$ref": "#/definitions/client.Payload" } } ], "responses": { "201": { "description": "Client created successfully", "schema": { "$ref": "#/definitions/models.Client" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/clients/{client_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a client by the provided ID.", "produces": [ "application/json" ], "tags": [ "clients" ], "summary": "Get a client by ID", "operationId": "get-client", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "client ID", "name": "client_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Client" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Client does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "description": "Update an existing client", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "clients" ], "summary": "Update client", "operationId": "update-client", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Client ID", "name": "client_id", "in": "path", "required": true }, { "description": "Client payload", "name": "client", "in": "body", "required": true, "schema": { "$ref": "#/definitions/client.Payload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Client does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes a client by the provided ID.", "produces": [ "application/json" ], "tags": [ "clients" ], "summary": "Delete a client by ID", "operationId": "delete-client", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "client ID", "name": "client_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Client does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/clients/{client_id}/restore": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Restores a client by the provided ID.", "produces": [ "application/json" ], "tags": [ "clients" ], "summary": "Restore a client by ID", "operationId": "restore-client", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "client ID", "name": "client_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Client does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/composite/tasks": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates the main task, subtasks, time blocks and time entries in bulk.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "composite" ], "summary": "Creates the main task, subtasks, time blocks and time entries in bulk", "operationId": "composite-create-task-old", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Tasks composite creation payload", "name": "composite", "in": "body", "required": true, "schema": { "$ref": "#/definitions/composite.CreateTasksPayload" } } ], "responses": { "201": { "description": "Composite task creation success", "schema": { "$ref": "#/definitions/composite.CreateTasksResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/context": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the server-derived workspace and organization IDs. Session authentication only; API-key callers are rejected.", "produces": [ "application/json" ], "tags": [ "workspace" ], "summary": "Get workspace context", "operationId": "get-workspace-context", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/mcp.ContextResponse" } }, "403": { "description": "User does not have access to the workspace", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/currency": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the workspace's consolidation/display currency (ISO 4217). Defaults to USD when none has been set.", "produces": [ "application/json" ], "tags": [ "workspace-settings" ], "summary": "Get workspace currency", "operationId": "get-workspace-currency", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Currency retrieved successfully", "schema": { "$ref": "#/definitions/workspace.Currency" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Sets the workspace's consolidation/display currency (ISO 4217). Requires workspace-admin rights.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "workspace-settings" ], "summary": "Set workspace currency", "operationId": "update-workspace-currency", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Currency payload", "name": "currency", "in": "body", "required": true, "schema": { "$ref": "#/definitions/workspace.UpdateCurrencyPayload" } } ], "responses": { "200": { "description": "Currency updated successfully", "schema": { "$ref": "#/definitions/workspace.Currency" } }, "400": { "description": "Invalid request body", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User is not authorized to update workspace currency", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/integrations/calendar": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "List calendar integrations, i.e. the email accounts connected.", "produces": [ "text/plain" ], "tags": [ "calendar" ], "summary": "List calendar integrations", "operationId": "calendar-integrations-list-old", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "List of integrations, aka connected emails", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.IntegrationWithCalendars" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/integrations/calendar/setup": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Connect a new calendar integration.", "produces": [ "text/plain" ], "tags": [ "calendar" ], "summary": "Setup calendar integration", "operationId": "calendar-integrations-setup-old", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "Calendar service provider which the calendars will be retrieved", "name": "provider", "in": "query", "required": true }, { "type": "string", "description": "Page to which the user will be redirected after authenticating", "name": "return_to", "in": "query" } ], "responses": { "302": { "description": "Redirect to oAuth URL", "schema": { "type": "string" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "status payment required: integration already exists", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/integrations/calendar/{integration_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "List calendars for a particular integration, i.e. the calendars available from the connected account.", "produces": [ "text/plain" ], "tags": [ "calendar" ], "summary": "List calendars for a particular integration", "operationId": "calendar-integrations-calendars-old", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "integration ID", "name": "integration_id", "in": "path", "required": true } ], "responses": { "200": { "description": "List of calendars", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Calendar" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Delete a calendar integration.", "produces": [ "text/plain" ], "tags": [ "calendar" ], "summary": "Delete a calendar integration", "operationId": "calendar-integration-delete-old", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "integration ID", "name": "integration_id", "in": "path", "required": true }, { "type": "boolean", "description": "When true, leave linked entities in place. Default false: future-planned calendar time entries are soft-deleted asynchronously; tasks and time blocks are retained.", "name": "preserve_entities", "in": "query" } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/integrations/calendar/{integration_id}/calendars/{calendar_id}": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Update calendar integration.", "produces": [ "text/plain" ], "tags": [ "calendar" ], "summary": "Update calendar integration", "operationId": "calendar-integrations-update-calendar-old", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "integration ID", "name": "integration_id", "in": "path", "required": true }, { "type": "integer", "description": "calendar ID", "name": "calendar_id", "in": "path", "required": true }, { "description": "Calendar object", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/models.Calendar" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/integrations/calendar/{integration_id}/calendars/{calendar_id}/settings": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Replaces the per-calendar settings for the given (user, calendar) pair. Idempotent PUT.", "consumes": [ "application/json" ], "tags": [ "calendar" ], "summary": "Update per-calendar settings", "operationId": "calendar-integrations-update-calendar-settings-old", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "integration ID", "name": "integration_id", "in": "path", "required": true }, { "type": "integer", "description": "calendar ID", "name": "calendar_id", "in": "path", "required": true }, { "description": "Calendar settings payload", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/calendar.calendarSettingsRequest" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request or validation failure", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/integrations/calendar/{integration_id}/reauth": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Re-request authorization for an existing calendar integration, refreshing its token. By\ndefault this also escalates to write scope (the \"sync everywhere\" upgrade flow); pass\npreserve_scope=true to re-request the integration's existing scopes instead.", "produces": [ "text/plain" ], "tags": [ "calendar" ], "summary": "Re-authorize calendar integration.", "operationId": "calendar-integrations-reauth-old", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "integration ID", "name": "integration_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "Page to which the user will be redirected after authenticating", "name": "return_to", "in": "query", "required": true }, { "type": "boolean", "description": "Re-request the integration's existing scopes instead of escalating to write", "name": "preserve_scope", "in": "query" } ], "responses": { "302": { "description": "Redirect to oAuth URL", "schema": { "type": "string" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Integration not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/integrations/calendar/{integration_id}/update": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Update integration.", "produces": [ "text/plain" ], "tags": [ "calendar" ], "summary": "Update integration", "operationId": "calendar-integrations-update-old", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "integration ID", "name": "integration_id", "in": "path", "required": true }, { "type": "boolean", "description": "Override the auto-track default stamped onto newly materialized calendars. Defaults to false when omitted.", "name": "focus_auto_track_default", "in": "query" } ], "responses": { "200": { "description": "List of calendars", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Calendar" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/milestones": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of milestones based on the provided workspace ID and filter params.", "consumes": [ "application/json" ], "produces": [ "application/json", "application/json" ], "tags": [ "milestones" ], "summary": "List milestones", "operationId": "list-milestones", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "name", "-name", "due_date", "-due_date", "completed_at", "-completed_at", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" }, { "type": "string", "format": "date", "description": "filter by due date from", "name": "due_date_from", "in": "query" }, { "type": "string", "format": "date", "description": "filter by due date to", "name": "due_date_to", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by project id", "name": "project_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by team id", "name": "team_id", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Page-models_Milestone" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new milestone.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "milestones" ], "summary": "Create milestone", "operationId": "create-milestone", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "milestone data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/milestone.Payload" } } ], "responses": { "201": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Milestone" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Milestone limit reached; upgrade required", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/milestones/stream": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of milestones based on the provided workspace ID and filter params.", "consumes": [ "application/json" ], "produces": [ "application/json", "application/json" ], "tags": [ "milestones" ], "summary": "List milestones", "operationId": "list-milestones-stream", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "enum": [ "name", "-name", "due_date", "-due_date", "completed_at", "-completed_at", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" }, { "type": "string", "format": "date", "description": "filter by due date from", "name": "due_date_from", "in": "query" }, { "type": "string", "format": "date", "description": "filter by due date to", "name": "due_date_to", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by project id", "name": "project_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "filter by team id", "name": "team_id", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Milestone" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/milestones/{milestone_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Get an existing milestone", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "milestones" ], "summary": "Get milestone", "operationId": "get-milestone", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "milestone ID", "name": "milestone_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Milestone" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Update an existing milestone", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "milestones" ], "summary": "Update milestone", "operationId": "update-milestone", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "milestone ID", "name": "milestone_id", "in": "path", "required": true }, { "description": "milestone data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/milestone.Payload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Delete an existing milestone", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "milestones" ], "summary": "Delete milestone", "operationId": "delete-milestone", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "milestone ID", "name": "milestone_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Partial update an existing milestone", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "milestones" ], "summary": "Partial update milestone", "operationId": "partial-update-milestone", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "milestone ID", "name": "milestone_id", "in": "path", "required": true }, { "description": "milestone data", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/milestone.PartialUpdatePayload" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/milestones/{milestone_id}/restore": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Restore a deleted milestone", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "milestones" ], "summary": "Restore milestone", "operationId": "restore-milestone", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "milestone ID", "name": "milestone_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/permissions": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the complete list of permissions for the current user in the specified workspace.\nThis combines unconditional permissions from the user's role with conditional permissions based on workspace settings.", "produces": [ "application/json" ], "tags": [ "workspace-settings" ], "summary": "Get current user's permissions in workspace", "operationId": "get-user-permissions", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Permissions retrieved successfully", "schema": { "$ref": "#/definitions/workspace.UserPermissionsResponse" } }, "403": { "description": "User does not have access to workspace", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/saved-views": { "get": { "description": "Get all saved views for the authenticated user with optional filtering and ordering", "produces": [ "application/json" ], "tags": [ "SavedViews" ], "summary": "List saved views", "parameters": [ { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "Filter saved views by name (partial match)", "name": "name", "in": "query" }, { "enum": [ "inbox", "archive", "board", "timeline", "project", "project.tasks", "project.board", "project.timeline", "projects", "reports.summary", "reports.detailed", "reports.utilization", "reports.workload", "reports.profitability" ], "type": "string", "description": "Filter saved views by type", "name": "type", "in": "query" }, { "enum": [ "name", "-name", "type", "-type", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Order by field", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.SavedView" } } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "description": "Create a new saved view for the authenticated user", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SavedViews" ], "summary": "Create a new saved view", "parameters": [ { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Saved view data", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/savedview.CreatePayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/models.SavedView" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/saved-views/{id}": { "get": { "description": "Retrieve a single saved view by ID for the authenticated user", "produces": [ "application/json" ], "tags": [ "SavedViews" ], "summary": "Get a saved view", "parameters": [ { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Saved view ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.SavedView" } }, "404": { "description": "Not Found", "schema": {} }, "500": { "description": "Internal Server Error", "schema": {} } } }, "delete": { "description": "Delete an existing saved view for the authenticated user", "tags": [ "SavedViews" ], "summary": "Delete a saved view", "parameters": [ { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Saved view ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "description": "Update an existing saved view for the authenticated user", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SavedViews" ], "summary": "Update a saved view", "parameters": [ { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Saved view ID", "name": "id", "in": "path", "required": true }, { "description": "Updated saved view data", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/savedview.UpdatePayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.SavedView" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/settings": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns permission settings for workspace roles. Settings control which roles have access to specific actions on clients, tags, and statuses.", "produces": [ "application/json" ], "tags": [ "workspace-settings" ], "summary": "Get workspace permission settings", "operationId": "get-workspace-settings", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Settings retrieved successfully", "schema": { "$ref": "#/definitions/workspace.Settings" } }, "403": { "description": "User is not authorized to view workspace settings", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Updates permission settings for workspace roles. Creates settings if they don't exist (upsert operation).\nThe settings object should map role IDs to their permissions.\nNote: Use role IDs as string keys (e.g., \"15\" for ws_admin, \"16\" for ws_manager, \"17\" for ws_user), not role codes.\nAvailable permissions:\n- Clients: create_client, rename_client, archive_client, delete_client\n- Statuses: create_status, update_status, delete_status\n- Tags: create_tags, update_tags, delete_tags\n```json\n{\n\"settings\": {\n\"15\": {\n\"create_client\": true,\n\"rename_client\": true,\n\"archive_client\": true,\n\"delete_client\": true,\n\"create_status\": true,\n\"update_status\": true,\n\"delete_status\": true,\n\"create_tags\": true,\n\"update_tags\": true,\n\"delete_tags\": true\n},\n\"16\": {\n\"create_client\": true,\n\"rename_client\": true,\n\"archive_client\": false,\n\"delete_client\": false,\n\"create_status\": true,\n\"update_status\": true,\n\"delete_status\": false,\n\"create_tags\": true,\n\"update_tags\": true,\n\"delete_tags\": false\n},\n\"17\": {\n\"create_client\": false,\n\"rename_client\": false,\n\"archive_client\": false,\n\"delete_client\": false,\n\"create_status\": false,\n\"update_status\": false,\n\"delete_status\": false,\n\"create_tags\": false,\n\"update_tags\": false,\n\"delete_tags\": false\n}\n}\n}\n```", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "workspace-settings" ], "summary": "Update workspace permission settings", "operationId": "update-workspace-settings", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Settings payload", "name": "settings", "in": "body", "required": true, "schema": { "$ref": "#/definitions/workspace.UpdatePayload" } } ], "responses": { "200": { "description": "Settings updated successfully", "schema": { "$ref": "#/definitions/workspace.Settings" } }, "400": { "description": "Invalid request body", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User is not authorized to update workspace settings", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/statuses": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of statuses based on the workspace ID.", "produces": [ "application/json" ], "tags": [ "statuses" ], "summary": "List statuses", "operationId": "list-statuses", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "filter by status name", "name": "name", "in": "query" }, { "enum": [ "todo", "in_progress", "done", "blocked" ], "type": "string", "description": "filter by status type", "name": "type", "in": "query" }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "name", "-name", "workspace_id", "-workspace_id", "created_at", "-created_at", "updated_at", "-updated_at", "position", "-position" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Page-models_Status" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new status with the provided details.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "statuses" ], "summary": "Create a new status", "operationId": "create-status", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Status payload", "name": "status", "in": "body", "required": true, "schema": { "$ref": "#/definitions/status.Payload" } } ], "responses": { "201": { "description": "Status created successfully", "schema": { "$ref": "#/definitions/models.Status" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/statuses/{status_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a status with the provided ID.", "produces": [ "application/json" ], "tags": [ "statuses" ], "summary": "Get status by ID", "operationId": "get-status", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "status ID", "name": "status_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Status" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Status not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "description": "Update an existing statuses", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "statuses" ], "summary": "Update status", "operationId": "update-status", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Status ID", "name": "status_id", "in": "path", "required": true }, { "description": "Status payload", "name": "status", "in": "body", "required": true, "schema": { "$ref": "#/definitions/status.Payload" } } ], "responses": { "200": { "description": "Successfully updated status", "schema": { "$ref": "#/definitions/models.Status" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Status not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes a status with the provided ID.", "produces": [ "application/json" ], "tags": [ "statuses" ], "summary": "Delete a status by ID", "operationId": "delete-status", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "statuses ID", "name": "status_id", "in": "path", "required": true } ], "responses": { "204": { "description": "Successfully deleted status" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Cannot delete default status", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Status not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/statuses/{status_id}/restore": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Restores a statuses by the provided ID.", "produces": [ "application/json" ], "tags": [ "statuses" ], "summary": "Restore a statuses by ID", "operationId": "restore-statuses", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "statuses ID", "name": "status_id", "in": "path", "required": true } ], "responses": { "204": { "description": "Successfully restored status" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Status not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/tags": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of tags based on the workspace ID.", "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "List tags", "operationId": "list-tags", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "string", "description": "filter by name", "name": "name", "in": "query" }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" }, { "type": "array", "items": { "enum": [ "name", "-name" ], "type": "string" }, "collectionFormat": "csv", "description": "order by", "name": "order_by", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by tag IDs", "name": "tag_id", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.PageWithTotal-models_Tag" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a new tag with the provided details.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Create a new tag", "operationId": "create-tag", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Tag payload", "name": "tag", "in": "body", "required": true, "schema": { "$ref": "#/definitions/tag.Payload" } } ], "responses": { "201": { "description": "Tag created successfully", "schema": { "$ref": "#/definitions/models.Tag" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/tags/bulk": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates several tags in one transaction. Names are compared case-insensitively both within the batch and against existing tags; any duplicate fails the whole batch.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Bulk create tags", "operationId": "bulk-create-tags", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Bulk create payload", "name": "bulkCreatePayload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/tag.BulkCreatePayload" } } ], "responses": { "201": { "description": "Tags created successfully", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Tag" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes several tags by the provided IDs. All-or-nothing: if any ID is unknown, outside the workspace, or already deleted, nothing is deleted.", "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Bulk delete tags", "operationId": "bulk-delete-tags", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "tag IDs to delete", "name": "ids", "in": "query", "required": true } ], "responses": { "204": { "description": "Successfully deleted tags" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "One or more tags do not exist or are already deleted", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/tags/bulk/restore": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Restores several tags by the provided IDs. All-or-nothing: if any ID is unknown or outside the workspace, nothing is restored, and a 400 is returned if restoring would leave two live tags sharing a name. Restoring a tag that is not deleted is a no-op.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Bulk restore tags", "operationId": "bulk-restore-tags", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Bulk restore payload", "name": "bulkRestorePayload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/tag.BulkRestorePayload" } } ], "responses": { "204": { "description": "Successfully restored tags" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "One or more tags do not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Another tag already holds this integration identity", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/tags/{tag_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a tag with the provided ID.", "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Get tag by ID", "operationId": "get-tag", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "tag ID", "name": "tag_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.Tag" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "description": "Update an existing tag", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Update tag", "operationId": "update-tag", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Tag ID", "name": "tag_id", "in": "path", "required": true }, { "description": "Tag payload", "name": "tag", "in": "body", "required": true, "schema": { "$ref": "#/definitions/tag.Payload" } } ], "responses": { "200": { "description": "Successfully updated tag", "schema": { "$ref": "#/definitions/models.Tag" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes a tag with the provided ID.", "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Delete a tag by ID", "operationId": "delete-tag", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "tag ID", "name": "tag_id", "in": "path", "required": true } ], "responses": { "204": { "description": "Successfully deleted tag" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/tags/{tag_id}/restore": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Restores a tag by the provided ID.", "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Restore a tag by ID", "operationId": "restore-tag", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "tag ID", "name": "tag_id", "in": "path", "required": true } ], "responses": { "204": { "description": "Successfully restored tag" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Another tag already holds this integration identity", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/task-constraints": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns required field constraints for tasks in the workspace.", "produces": [ "application/json" ], "tags": [ "task-constraints" ], "summary": "Get task constraints", "operationId": "get-task-constraints", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Constraints retrieved successfully", "schema": { "$ref": "#/definitions/taskconstraints.Response" } }, "402": { "description": "Feature not available on current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User is not authorized to view task constraints", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Updates required field constraints for tasks in the workspace. Creates if not present.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "task-constraints" ], "summary": "Update task constraints", "operationId": "upsert-task-constraints", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Constraints payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/taskconstraints.UpsertPayload" } } ], "responses": { "200": { "description": "Constraints updated successfully", "schema": { "$ref": "#/definitions/taskconstraints.Response" } }, "400": { "description": "Invalid request body", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Feature not available on current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User is not authorized to update task constraints", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/time-entry-constraints": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns required field constraints for time entries in the workspace.", "produces": [ "application/json" ], "tags": [ "time-entry-constraints" ], "summary": "Get time entry constraints", "operationId": "get-time-entry-constraints", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Constraints retrieved successfully", "schema": { "$ref": "#/definitions/timeentryconstraints.Response" } }, "402": { "description": "Feature not available on current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User is not authorized to view time entry constraints", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Updates required field constraints for time entries in the workspace. Creates if not present.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entry-constraints" ], "summary": "Update time entry constraints", "operationId": "upsert-time-entry-constraints", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Constraints payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timeentryconstraints.UpsertPayload" } } ], "responses": { "200": { "description": "Constraints updated successfully", "schema": { "$ref": "#/definitions/timeentryconstraints.Response" } }, "400": { "description": "Invalid request body", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Feature not available on current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User is not authorized to update time entry constraints", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/users/me/settings": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns merged user settings for the workspace (workspace-specific overrides combined with global settings).", "produces": [ "application/json" ], "tags": [ "user-workspace-settings" ], "summary": "Get user workspace settings", "operationId": "get-user-workspace-settings", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Settings retrieved successfully", "schema": { "$ref": "#/definitions/userworkspace.MergedUserWorkspaceSettings" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Updates workspace-specific user settings. Setting a value to null removes the workspace override and reverts to the global setting.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "user-workspace-settings" ], "summary": "Partial update user workspace settings", "operationId": "partial-update-user-workspace-settings", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Settings payload", "name": "settings", "in": "body", "required": true, "schema": { "$ref": "#/definitions/userworkspace.PartialUpdatePayload" } } ], "responses": { "200": { "description": "Successfully updated", "schema": { "$ref": "#/definitions/models.UserWorkspaceSettings" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/utilization-target": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the workspace's utilization-target percent (1-100). Default 80 when unset.", "produces": [ "application/json" ], "tags": [ "utilization-target" ], "summary": "Get workspace utilization target percentage", "operationId": "get-utilization-target", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Target retrieved", "schema": { "$ref": "#/definitions/utilizationtarget.Target" } }, "402": { "description": "Plan does not include the Utilization report feature", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User is not authorized to view the utilization target", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Sets the workspace's utilization-target percent (1-100).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "utilization-target" ], "summary": "Update workspace utilization target percentage", "operationId": "update-utilization-target", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Target percentage payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/utilizationtarget.UpdatePayload" } } ], "responses": { "200": { "description": "Target updated", "schema": { "$ref": "#/definitions/utilizationtarget.Target" } }, "400": { "description": "Invalid request body", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Plan does not include the Utilization report feature", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User is not authorized to manage the utilization target", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/{organization_id}/workspaces/{workspace_id}/tracking/current": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Get current tracked time entry.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tracking-deprecated" ], "summary": "Get current tracked time entry (legacy)", "operationId": "get-tracked-time-entry", "deprecated": true, "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Time entry", "schema": { "$ref": "#/definitions/models.TimeEntry" } }, "204": { "description": "Not tracking a time entry" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/{organization_id}/workspaces/{workspace_id}/tracking/start": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Start tracking time entry. If a running entry already exists it is automatically stopped and the new entry is returned.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tracking-deprecated" ], "summary": "Start tracking time entry (legacy)", "operationId": "start-tracking", "deprecated": true, "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/timeentry.StartTrackingPayload" } } ], "responses": { "200": { "description": "Time entry", "schema": { "$ref": "#/definitions/models.TimeEntry" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "User task does not exist", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Required field is missing (error=required_fields_missing) or is being cleared on a grandfathered entry (error=required_fields_deletion)", "schema": { "$ref": "#/definitions/timeentryconstraints.RequiredFieldsErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/{organization_id}/workspaces/{workspace_id}/tracking/stop": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Stop tracking time entry.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tracking-deprecated" ], "summary": "Stop tracking time entry (legacy)", "operationId": "stop-tracking", "deprecated": true, "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "payload", "name": "payload", "in": "body", "schema": { "$ref": "#/definitions/timeentry.StopTrackingPayload" } } ], "responses": { "200": { "description": "Time entry", "schema": { "$ref": "#/definitions/models.TimeEntry" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not tracking a time entry", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Required field is missing (error=required_fields_missing) or is being cleared on a grandfathered entry (error=required_fields_deletion)", "schema": { "$ref": "#/definitions/timeentryconstraints.RequiredFieldsErrorResponse" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } } }, "definitions": { "alert.CreatePayload": { "type": "object", "required": [ "config", "rule_type" ], "properties": { "config": { "$ref": "#/definitions/alert.RuleConfig" }, "project_id": { "type": "integer" }, "recipient_group_ids": { "type": "array", "items": { "type": "integer" } }, "recipient_roles": { "type": "array", "items": { "type": "string" } }, "recipient_user_ids": { "type": "array", "items": { "type": "integer" } }, "rule_type": { "type": "string", "enum": [ "time_estimate", "fixed_fee", "time_tracking_reminder" ] } } }, "alert.PartialUpdatePayload": { "type": "object", "properties": { "config": { "$ref": "#/definitions/alert.RuleConfig" }, "recipient_group_ids": { "type": "array", "items": { "type": "integer" } }, "recipient_roles": { "type": "array", "items": { "type": "string" } }, "recipient_user_ids": { "type": "array", "items": { "type": "integer" } }, "rule_type": { "type": "string", "enum": [ "time_estimate", "fixed_fee", "time_tracking_reminder" ] } } }, "alert.Rule": { "type": "object", "required": [ "config", "created_at", "created_by", "id", "recipient_group_ids", "recipient_roles", "recipient_user_ids", "rule_type", "updated_at", "workspace_id" ], "properties": { "config": { "$ref": "#/definitions/alert.RuleConfig" }, "created_at": { "type": "string", "format": "full-date" }, "created_by": { "type": "integer" }, "deleted_at": { "type": "string", "format": "full-date" }, "id": { "type": "integer" }, "project_id": { "type": "integer" }, "recipient_group_ids": { "type": "array", "items": { "type": "integer" } }, "recipient_roles": { "type": "array", "items": { "type": "string" } }, "recipient_user_ids": { "type": "array", "items": { "type": "integer" } }, "rule_type": { "type": "string" }, "updated_at": { "type": "string", "format": "full-date" }, "workspace_id": { "type": "integer" } } }, "alert.RuleConfig": { "type": "object", "properties": { "frequency": { "description": "\"day\" or \"week\"", "type": "string" }, "target_seconds": { "description": "Reminder fields", "type": "integer" }, "threshold_pct": { "description": "Alert fields", "type": "integer" } } }, "api.VersionResponse": { "type": "object", "required": [ "name", "number", "revision" ], "properties": { "name": { "type": "string" }, "number": { "type": "integer" }, "revision": { "type": "string" } } }, "attachmentstorage.Usage": { "type": "object", "required": [ "enforced", "limit_bytes", "used_bytes" ], "properties": { "enforced": { "type": "boolean" }, "limit_bytes": { "type": "integer" }, "used_bytes": { "type": "integer" } } }, "auditlog.ClientSummary": { "type": "object", "required": [ "id", "name", "workspace_id" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "workspace_id": { "type": "integer" } } }, "auditlog.CustomFieldOptionSummary": { "type": "object", "required": [ "custom_field_id", "id", "name", "workspace_id" ], "properties": { "custom_field_id": { "type": "integer" }, "deleted_at": { "type": "string", "format": "date-time" }, "id": { "type": "integer" }, "name": { "type": "string" }, "workspace_id": { "type": "integer" } } }, "auditlog.CustomFieldSummary": { "type": "object", "required": [ "entity_type", "field_type", "id", "name", "status", "workspace_id" ], "properties": { "deleted_at": { "type": "string", "format": "date-time" }, "entity_type": { "type": "string", "enum": [ "task", "project", "user", "time_entry" ] }, "field_type": { "type": "string", "enum": [ "select", "multi_select", "text", "number", "date", "checkbox", "users" ] }, "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "pending_delete", "deleted" ] }, "workspace_id": { "type": "integer" } } }, "auditlog.GroupSummary": { "type": "object", "required": [ "group_id", "name", "user_ids" ], "properties": { "group_id": { "type": "integer" }, "name": { "type": "string" }, "user_ids": { "type": "array", "items": { "type": "integer" } } } }, "auditlog.ProjectSummary": { "type": "object", "required": [ "id", "name", "workspace_id" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "workspace_id": { "type": "integer" } } }, "auditlog.Response": { "type": "object", "required": [ "client_summaries", "custom_field_option_summaries", "custom_field_summaries", "events", "group_summaries", "project_summaries", "task_summaries", "user_summaries", "workspace_summaries" ], "properties": { "client_summaries": { "type": "object", "additionalProperties": { "$ref": "#/definitions/auditlog.ClientSummary" } }, "custom_field_option_summaries": { "type": "object", "additionalProperties": { "$ref": "#/definitions/auditlog.CustomFieldOptionSummary" } }, "custom_field_summaries": { "type": "object", "additionalProperties": { "$ref": "#/definitions/auditlog.CustomFieldSummary" } }, "events": { "type": "array", "items": { "$ref": "#/definitions/models.StreamEvent" } }, "group_summaries": { "type": "object", "additionalProperties": { "$ref": "#/definitions/auditlog.GroupSummary" } }, "project_summaries": { "type": "object", "additionalProperties": { "$ref": "#/definitions/auditlog.ProjectSummary" } }, "task_summaries": { "type": "object", "additionalProperties": { "$ref": "#/definitions/auditlog.TaskSummary" } }, "user_summaries": { "type": "object", "additionalProperties": { "$ref": "#/definitions/auditlog.UserSummary" } }, "workspace_summaries": { "type": "object", "additionalProperties": { "$ref": "#/definitions/auditlog.WorkspaceSummary" } } } }, "auditlog.TaskSummary": { "type": "object", "required": [ "id", "name", "project_id" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "project_id": { "type": "integer" } } }, "auditlog.UserSummary": { "type": "object", "required": [ "email", "id", "name", "user_account_id" ], "properties": { "email": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "user_account_id": { "type": "integer" } } }, "auditlog.WorkspaceSummary": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "authentication.UserMetadata": { "type": "object", "required": [ "flags", "has_tasks", "platform_presence" ], "properties": { "flags": { "type": "array", "items": { "$ref": "#/definitions/betafeatures.BetaFeatureUser" } }, "has_tasks": { "type": "boolean" }, "platform_presence": { "type": "array", "items": { "$ref": "#/definitions/presence.PlatformLastSeen" } } } }, "backoffice.CustomFieldsView": { "type": "object", "required": [ "count", "has_custom_fields" ], "properties": { "count": { "type": "integer" }, "has_custom_fields": { "type": "boolean" } } }, "backoffice.ImportJobView": { "type": "object", "required": [ "created_at", "import_scope", "job_id", "progress", "progress_details", "progress_stage", "result_summary", "run_id", "source_product_id", "status", "updated_at", "user_id" ], "properties": { "created_at": { "type": "string" }, "import_scope": { "type": "string" }, "job_id": { "type": "string" }, "progress": { "type": "integer" }, "progress_details": { "$ref": "#/definitions/importer.ImportProgressDetails" }, "progress_stage": { "type": "string" }, "result_summary": { "$ref": "#/definitions/importer.ImportResultSummary" }, "run_id": { "type": "string" }, "source_product_id": { "type": "integer" }, "status": { "type": "string" }, "updated_at": { "type": "string" }, "user_id": { "type": "integer" } } }, "backoffice.TaskConstraintsView": { "type": "object", "required": [ "description_present", "enabled", "project_present", "tag_present" ], "properties": { "description_present": { "type": "boolean" }, "enabled": { "type": "boolean" }, "project_present": { "type": "boolean" }, "tag_present": { "type": "boolean" } } }, "backoffice.TimeEntriesPage": { "type": "object", "required": [ "data", "next_cursor", "prev_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/backoffice.TimeEntryView" } }, "next_cursor": { "type": "string", "x-nullable": true }, "prev_cursor": { "type": "string", "x-nullable": true } } }, "backoffice.TimeEntriesTotal": { "type": "object", "required": [ "total" ], "properties": { "total": { "type": "integer" } } }, "backoffice.TimeEntryConstraintsView": { "type": "object", "required": [ "description_present", "enabled", "project_present", "task_present" ], "properties": { "description_present": { "type": "boolean" }, "enabled": { "type": "boolean" }, "project_present": { "type": "boolean" }, "task_present": { "type": "boolean" } } }, "backoffice.TimeEntryView": { "type": "object", "required": [ "billable", "created_at", "id", "type", "updated_at", "workspace_id" ], "properties": { "archived_at": { "type": "string", "format": "date-time" }, "billable": { "type": "boolean" }, "calendar_event_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "duration": { "type": "integer" }, "id": { "type": "integer" }, "planned_duration": { "type": "integer" }, "planned_start": { "type": "string", "format": "date-time" }, "project_id": { "type": "integer" }, "start": { "type": "string", "format": "date-time" }, "task_id": { "type": "integer" }, "task_name": { "type": "string" }, "type": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "backoffice.WorkspaceOverviewResponse": { "type": "object", "required": [ "created_at", "id", "name", "organization_id", "updated_at" ], "properties": { "created_at": { "type": "string" }, "custom_fields": { "allOf": [ { "$ref": "#/definitions/backoffice.CustomFieldsView" } ], "x-nullable": true }, "deleted_at": { "type": "string", "format": "date-time" }, "id": { "type": "integer" }, "name": { "type": "string" }, "organization_id": { "type": "integer" }, "organization_name": { "type": "string" }, "permission_overrides": { "$ref": "#/definitions/workspace.JSONSettings" }, "task_constraints": { "allOf": [ { "$ref": "#/definitions/backoffice.TaskConstraintsView" } ], "x-nullable": true }, "time_entry_constraints": { "allOf": [ { "$ref": "#/definitions/backoffice.TimeEntryConstraintsView" } ], "x-nullable": true }, "toggl_products": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "string" } } }, "backoffice.betaFeaturePayload": { "type": "object", "required": [ "code", "comment", "value" ], "properties": { "code": { "type": "string" }, "comment": { "type": "string" }, "value": { "type": "boolean" } } }, "backoffice.timeEntryBulkRestorePayload": { "type": "object", "required": [ "comment", "time_entry_ids" ], "properties": { "comment": { "type": "string", "maxLength": 2000, "minLength": 10 }, "time_entry_ids": { "type": "array", "minItems": 1, "items": { "type": "integer" } } } }, "backoffice.timeEntryMutationPayload": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "string", "maxLength": 2000, "minLength": 10 } } }, "betafeatures.BetaFeature": { "type": "object", "required": [ "active_users", "beta_feature_id", "code", "description", "enabled" ], "properties": { "active_users": { "description": "ActiveUsers Number of users that have feature activated", "type": "integer" }, "beta_feature_id": { "description": "Feature ID", "type": "integer" }, "code": { "description": "Feature code", "type": "string" }, "description": { "description": "Feature description, omitted if empty", "type": "string" }, "enabled": { "description": "Whether the feature is enabled", "type": "boolean" } } }, "betafeatures.BetaFeaturePayload": { "type": "object", "required": [ "code", "description" ], "properties": { "code": { "description": "Feature code", "type": "string" }, "description": { "description": "Feature description, omitted if empty", "type": "string" } } }, "betafeatures.BetaFeatureUser": { "type": "object", "required": [ "beta_feature_id", "code", "description", "enabled_for_all", "enabled_for_user" ], "properties": { "beta_feature_id": { "description": "Feature ID", "type": "integer" }, "code": { "description": "Feature code", "type": "string" }, "description": { "description": "Feature description, omitted if empty", "type": "string" }, "enabled_for_all": { "description": "Whether the feature is enabled for all users", "type": "boolean" }, "enabled_for_user": { "description": "Whether the feature is enabled for current user.", "type": "boolean" } } }, "calendar.calendarSettingsRequest": { "type": "object", "properties": { "ical_uids": { "type": "array", "maxItems": 500, "items": { "type": "string" } } } }, "calendar.mappingRequest": { "type": "object", "required": [ "title" ], "properties": { "project_id": { "type": "integer" }, "task_id": { "type": "integer" }, "title": { "type": "string" } } }, "client.Payload": { "type": "object", "required": [ "name" ], "properties": { "currency": { "description": "Currency is the client's optional default display currency (ISO 4217). Omitted or\nnull means the client falls back to the workspace currency. On update (PUT) it is\nset directly, so send it to set/keep it or null to clear.", "type": "string" }, "name": { "type": "string" } } }, "client.UserGroupExtended": { "type": "object", "required": [ "created_at", "deleted_at", "display_name", "focus_role_id", "organization_user_id", "track_role_id", "updated_at", "user_account_id", "user_group_id", "work_role_id" ], "properties": { "created_at": { "type": "string", "example": "2021-09-01T00:00:00Z" }, "deleted_at": { "type": "string", "example": "2021-09-01T00:00:00Z" }, "display_name": { "type": "string", "example": "John Doe" }, "focus_role_id": { "type": "integer", "example": 2 }, "organization_user_id": { "type": "integer", "example": 20000000 }, "track_role_id": { "type": "integer", "example": 1 }, "updated_at": { "type": "string", "example": "2021-09-01T00:00:00Z" }, "user_account_id": { "type": "integer", "example": 20000000 }, "user_group_id": { "type": "integer", "example": 20000000 }, "work_role_id": { "type": "integer", "example": 3 } } }, "client.UserGroupInfoResponse": { "type": "object", "required": [ "emoji", "id", "name" ], "properties": { "emoji": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } } }, "client.WorkspaceGroupExtended": { "type": "object", "required": [ "created_at", "deleted_at", "focus_role_id", "name", "products", "updated_at", "workspace_group_id", "workspace_id" ], "properties": { "created_at": { "type": "string", "example": "2021-09-01T00:00:00Z" }, "deleted_at": { "type": "string", "example": "2021-09-01T00:00:00Z" }, "focus_role_id": { "type": "integer", "example": 17 }, "name": { "type": "string", "example": "Workspace Name" }, "products": { "type": "array", "items": { "type": "string" }, "example": [ "focus", "track" ] }, "updated_at": { "type": "string", "example": "2021-09-01T00:00:00Z" }, "workspace_group_id": { "type": "integer", "example": 20000000 }, "workspace_id": { "type": "integer", "example": 20000000 } } }, "composite.CreatePayload": { "type": "object", "required": [ "name" ], "properties": { "allocation_unit": { "type": "string", "default": "flat", "enum": [ "percent", "flat" ] }, "assignee_user_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "auto_log_time": { "type": "boolean" }, "billable": { "type": "boolean" }, "color": { "type": "string" }, "custom_fields": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" }, "end_date": { "type": "string", "format": "date" }, "estimate_type": { "type": "string", "enum": [ "daily", "total" ] }, "estimated_mins": { "type": "integer" }, "integration_ext_id": { "type": "integer" }, "integration_source": { "type": "string" }, "name": { "type": "string" }, "notes": { "type": "string" }, "parent_task_id": { "type": "integer" }, "pinned": { "type": "boolean" }, "position": { "type": "integer", "x-nullable": true }, "priority": { "type": "string", "enum": [ "none", "low", "medium", "high" ] }, "priority_at": { "type": "string", "format": "date" }, "private": { "type": "boolean" }, "project_id": { "type": "integer" }, "recurring_task_id": { "type": "integer" }, "rrule": { "type": "string", "x-nullable": true }, "start_date": { "type": "string", "format": "date" }, "status_id": { "type": "integer" }, "tag_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "team_assignee_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true } } }, "composite.CreateProjectPayload": { "type": "object", "required": [ "project" ], "properties": { "billable_rates": { "description": "The billable rates to be created alongside the project. Uses the\nrate package payload shape (inclusive [start_date, end_date], integer cents).", "type": "array", "items": { "$ref": "#/definitions/rate.NewRatePayload" } }, "members": { "description": "User data, and other membership details for adding members to the project.", "allOf": [ { "$ref": "#/definitions/projectuser.PostProjectMembers" } ] }, "milestones": { "description": "The milestones to be created alongside the project.", "type": "array", "items": { "$ref": "#/definitions/milestone.Payload" } }, "project": { "description": "The project to be created", "allOf": [ { "$ref": "#/definitions/project.Payload" } ] }, "rates": { "description": "The rates to be created alongside the project.", "type": "array", "items": { "$ref": "#/definitions/project.NewRate" } } } }, "composite.CreateProjectResponse": { "type": "object", "required": [ "billable_rates", "milestones", "project", "rates" ], "properties": { "billable_rates": { "description": "Billable rates that were created (rate package shape)", "type": "array", "items": { "$ref": "#/definitions/rate.RateAPI" } }, "milestones": { "description": "Milestones that were created", "type": "array", "items": { "$ref": "#/definitions/models.Milestone" } }, "project": { "description": "Project that was created", "allOf": [ { "$ref": "#/definitions/models.Project" } ] }, "rates": { "description": "Project rates that were created (legacy shape)", "type": "array", "items": { "$ref": "#/definitions/project.RateAPI" } } } }, "composite.CreateTasksPayload": { "type": "object", "required": [ "task" ], "properties": { "estimate_allocations": { "description": "EstimateAllocations are the main task's estimate allocations, created\nafter the task itself. Their value kind must match the task's\nallocation_unit.", "type": "array", "maxItems": 100, "items": { "$ref": "#/definitions/taskestimateallocation.AllocationValues" } }, "subtasks": { "type": "array", "items": { "$ref": "#/definitions/task.CreatePayloadWithoutParentID" } }, "task": { "$ref": "#/definitions/composite.CreatePayload" }, "time_blocks": { "type": "array", "items": { "$ref": "#/definitions/timeblock.Payload" } }, "time_entry": { "$ref": "#/definitions/composite.TimeEntryPayloadWithTimeBlock" } } }, "composite.CreateTasksResponse": { "type": "object", "required": [ "estimate_allocations", "subtasks", "task", "time_blocks", "time_entry" ], "properties": { "estimate_allocations": { "type": "array", "items": { "$ref": "#/definitions/models.TaskEstimateAllocation" } }, "subtasks": { "type": "array", "items": { "$ref": "#/definitions/models.Task" } }, "task": { "$ref": "#/definitions/models.Task" }, "time_blocks": { "type": "array", "items": { "$ref": "#/definitions/models.TimeBlock" } }, "time_entry": { "$ref": "#/definitions/models.TimeEntry" } } }, "composite.TimeEntryPayloadWithTimeBlock": { "type": "object", "required": [ "type" ], "properties": { "calendar_event_id": { "type": "integer" }, "description": { "type": "string" }, "duration": { "type": "integer", "minimum": 0 }, "planned_at": { "type": "string", "format": "date-time" }, "planned_duration": { "type": "integer", "minimum": 0 }, "planned_start": { "type": "string", "format": "date-time" }, "start": { "type": "string", "format": "date-time" }, "tag_ids": { "description": "TagIDs sets a manual tag override at creation (entry-authoritative,\nincluding an explicit empty array). Absent/null = no override: the\nentry inherits the linked task's tags.", "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "time_block": { "$ref": "#/definitions/timeblock.Payload" }, "time_block_id": { "type": "integer" }, "tracked_at": { "type": "string", "format": "date-time" }, "type": { "description": "The type of time entry. This could either be an activity, or a break.", "enum": [ "activity", "break" ], "allOf": [ { "$ref": "#/definitions/models.TimeEntryType" } ] } } }, "csv.ColumnFormat": { "type": "object", "properties": { "date_format": { "type": "string" }, "duration_format": { "type": "string" }, "tag_separator": { "type": "string" }, "time_format": { "type": "string" } } }, "csv.ColumnMapping": { "type": "object", "required": [ "entity", "field" ], "properties": { "entity": { "type": "string" }, "field": { "type": "string" }, "format": { "$ref": "#/definitions/csv.ColumnFormat" }, "key": { "type": "boolean" }, "literal": { "type": "string" }, "resolve_by": { "type": "string" }, "source_column": { "type": "string" } } }, "csv.ConfirmRequest": { "type": "object", "properties": { "match_existing_only": { "description": "MatchExistingOnly switches the import into match-only mode: clients,\nprojects, tasks, and users are matched against existing rows and never\ncreated. Unmatched structural rows — and the time entries that depend on\nthem — are skipped instead of creating new entities. Users are matched\nagainst existing workspace members only and never invited; a time entry\nwhose user isn't an existing member is skipped rather than routed to the\nimporting user. Time entries whose task and user are matched are still\nimported onto the existing task.\nClient and project names match exactly (case- and whitespace-sensitive),\nwhile task names match case- and whitespace-insensitively; check the\ncasing of skipped client/project rows before re-uploading.\n\nA project match covers archived, completed and inactive projects, not only\nthe ones visible in the default project list — so a row can update a\nproject an admin no longer thinks of as live. Recurring templates are the\none exception: they are never matched, because a write to a template is\ninherited by every instance created from it afterwards.\n\nA matched project is still updated from its row: custom field values are\nmerged in (values the CSV doesn't map are preserved), tags are linked,\nmembers and managers are granted — an existing member listed as a manager\nis promoted, and nobody is ever demoted — and billable is set when the row\ncarries a value, left alone when the cell is blank or the column unmapped.\nThe project's client binding is never changed. Linking a tag that doesn't\nexist yet creates that tag; nothing else is created. These updates are NOT\nreverted by the revert endpoint, which only removes rows the import\ncreated.\n\nA matched task is updated from its row the same way: custom field values\nare merged in, tags are linked, assignees are added — never removed — and\ndescription, estimated_minutes, start_date, end_date and billable are each\nwritten when the row carries a value and left alone when the cell is blank\nor the column unmapped. The task's project, client and parent bindings are\nnever changed. archived is the one mapped task column this mode does not\napply: archiving a task has to cascade to its subtasks and time entries,\nwhich an import cannot do at CSV scale, so the column is read only when a\ntask is created. Like the project updates, none of this is reverted.\n\nTwo task matches this mode refuses to write to, skipping the row with a\nwarning rather than guessing: a name that several live tasks share under\nthe same project and parent, and a task belonging to a recurring series.\nThe series parent carries the recurrence rule and every instance the\ngenerator creates afterwards inherits its description, estimate, dates,\ntags, assignees and custom field values, so one row would reshape the whole\nfuture series with no way to undo it.\n\nA matched client stays untouched, since its row carries only its name,\nwhich is the match key.\n\nA matched user is not invited, but a mapped role column IS applied to\nthem: their Focus role in this workspace is changed to the one the row\nnames, and their roles in other products are left as they are.\nOrganization admins and the account running the import are skipped. Unlike\nthe project and task updates above, this one IS reverted — the previous\nrole is saved before the change and put back by the revert endpoint.\n\nA field-catalog import (the custom_field entity) has no matching behavior\nto fall back to — it either creates fields and options or it doesn't —\nso this mode skips every custom_field row outright, with no fields\ncreated and no options added to existing fields.", "type": "boolean" }, "send_invites": { "type": "boolean" } } }, "csv.CreateProfileFromFileRequest": { "type": "object", "required": [ "file_id", "name" ], "properties": { "file_id": { "type": "integer" }, "name": { "type": "string" }, "source_product": { "type": "string" } } }, "csv.CreateProfileRequest": { "type": "object", "required": [ "column_mappings", "headers", "name" ], "properties": { "column_mappings": { "type": "array", "items": { "$ref": "#/definitions/csv.ColumnMapping" } }, "headers": { "type": "array", "items": { "type": "string" } }, "metadata": { "$ref": "#/definitions/csv.MappingMetadata" }, "name": { "type": "string" }, "source_product": { "type": "string" } } }, "csv.DryRunFailure": { "type": "object", "required": [ "category", "entity", "reason" ], "properties": { "category": { "type": "string" }, "entity": { "description": "Entity is the plural JSON entity name (clients, projects, tasks, tags,\nusers, teams, time_entries, custom_fields, project_rates,\nproject_member_rates, member_rates, member_costs, member_working_hours,\nmember_roles, member_rate_segments, member_cost_segments).", "type": "string" }, "name": { "description": "Name is omitted for failures with no entity name (e.g. a blank/unmapped\ntime-entry task), so it's optional in the API schema.", "type": "string" }, "reason": { "type": "string" }, "row": { "description": "Row is the 1-based CSV source line (including the header, matching\nCsvValidationError.Row) the failing row came from — the first occurrence for\ndeduplicated master-data. Omitted (0) when the line isn't known.", "type": "integer" } } }, "csv.DryRunRequest": { "type": "object", "properties": { "match_existing_only": { "description": "MatchExistingOnly previews a match-only import: unmatched clients,\nprojects, tasks, and users are reported as would-be-skipped instead of\nwould-create (users are never invited), while a matched project's or task's\nrow values are validated for warnings. See ConfirmRequest.MatchExistingOnly.", "type": "boolean" }, "send_invites": { "type": "boolean" } } }, "csv.DryRunResult": { "type": "object", "required": [ "counts", "match_existing_only" ], "properties": { "computed_at": { "description": "ComputedAt is set by the finalize activity when the dry-run completes.", "type": "string" }, "counts": { "description": "Counts holds per entity type: total / created (would-create) / updated\n(would write to an existing row) / matched (reused existing, untouched) /\nskipped (dropped — unmatched + create-new disabled) / failed, mirroring\nthe import-time Stats shape. See EntityStats.", "allOf": [ { "$ref": "#/definitions/csv.EntityCounts" } ] }, "failures": { "description": "Failures is a capped sample of rows that would be skipped or fail, each\ncategorized (see DryRunFailure* constants) so the UI can separate fixable\nCSV issues from transient DB errors.", "type": "array", "items": { "$ref": "#/definitions/csv.DryRunFailure" } }, "mapping_hash": { "description": "MappingHash is the fingerprint of the effective inputs this result was\ncomputed against. The API compares it to the upload's current hash to flag\na result as stale after the mapping changes. The mode toggle below is\nintentionally excluded from the hash — it changes counts but not the\nunderlying data — so it's surfaced separately for the FE to compare against\nthe user's current selection.", "type": "string" }, "match_existing_only": { "description": "MatchExistingOnly records the mode this result was computed in. The FE\nre-runs when the user's current toggle differs, since the counts (created\nvs would-be-skipped) only hold for the mode they were computed in.", "type": "boolean" }, "successes": { "description": "Successes is a capped sample of rows a real import would create, update or\nmatch, so the preview can show a sample of the data being imported\nalongside the flagged rows in Failures — not just the errors. They carry\nno reason; the FE renders them with a status column driven by Status.", "type": "array", "items": { "$ref": "#/definitions/csv.DryRunSuccess" } }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "csv.DryRunSuccess": { "type": "object", "required": [ "entity", "status" ], "properties": { "entity": { "description": "Entity is the plural JSON entity name (clients, projects, tasks, tags,\nusers, teams, time_entries, custom_fields, project_rates,\nproject_member_rates, member_rates, member_costs, member_working_hours,\nmember_roles, member_rate_segments, member_cost_segments), stamped by the\naggregator\nlike DryRunFailure.Entity.", "type": "string" }, "name": { "description": "Name is the entity name (email for users). Omitted for rows with no name\nof their own (e.g. a time entry).", "type": "string" }, "row": { "description": "Row is the 1-based CSV source line, matching DryRunFailure.Row. Omitted (0)\nwhen the line isn't known.", "type": "integer" }, "status": { "description": "Status is the would-be outcome: created (net-new), updated (existing row\nwritten to) or matched (reused existing, untouched). See DryRunRowCreated /\nDryRunRowUpdated / DryRunRowMatched.", "type": "string" } } }, "csv.EntityCounts": { "type": "object", "properties": { "clients": { "$ref": "#/definitions/csv.EntityStats" }, "custom_fields": { "$ref": "#/definitions/csv.EntityStats" }, "member_cost_segments": { "$ref": "#/definitions/csv.EntityStats" }, "member_costs": { "$ref": "#/definitions/csv.EntityStats" }, "member_rate_segments": { "description": "MemberRateSegments and MemberCostSegments count the TIMELINE path: several\nrows assembling one member's rate or cost history. Deliberately separate\nfrom MemberRates and MemberCosts above, which count the single-cell\nuser.rate and user.cost path. Same table on the backend, but one writes a\nsegment effective today and the other replaces a whole history, so a\ncombined count would describe neither. The FE sums each pair into one card\nbecause an admin reading a total does not care which mapping produced it.", "allOf": [ { "$ref": "#/definitions/csv.EntityStats" } ] }, "member_rates": { "$ref": "#/definitions/csv.EntityStats" }, "member_roles": { "description": "MemberRoles counts workspace role changes applied to members who already\nexist. Separate from Users, which counts the invites: a role change writes\nto somebody the import did not create, so folding it into Users would tell\nan admin they invited people they did not.", "allOf": [ { "$ref": "#/definitions/csv.EntityStats" } ] }, "member_working_hours": { "$ref": "#/definitions/csv.EntityStats" }, "project_member_rates": { "$ref": "#/definitions/csv.EntityStats" }, "project_rates": { "$ref": "#/definitions/csv.EntityStats" }, "projects": { "$ref": "#/definitions/csv.EntityStats" }, "tags": { "$ref": "#/definitions/csv.EntityStats" }, "tasks": { "$ref": "#/definitions/csv.EntityStats" }, "teams": { "$ref": "#/definitions/csv.EntityStats" }, "time_entries": { "$ref": "#/definitions/csv.EntityStats" }, "users": { "$ref": "#/definitions/csv.EntityStats" } } }, "csv.EntityStats": { "type": "object", "required": [ "created", "failed", "matched", "skipped", "total" ], "properties": { "created": { "description": "Created is net-new rows (would-create in a dry-run).", "type": "integer" }, "failed": { "description": "Failed is rows that errored (validation / DB).", "type": "integer" }, "matched": { "description": "Matched is rows reused from an existing entity found by key — no write.", "type": "integer" }, "options_added": { "description": "OptionsAdded is custom_field-only: select options the import wrote onto\nfields it matched rather than created. It counts options, not rows — the\nrows themselves are the custom_field entries in Updated — so it is the\nonly field here outside the total identity. In a dry-run it reads as\nwould-add, the same way Created does. Zero for every other entity type.\nCounts only options this import actually wrote: one that turned out to\nalready exist (a concurrent writer won the race) leaves the row Matched\nbut is not counted here.", "type": "integer" }, "skipped": { "description": "Skipped is rows dropped because their entity/dependency wasn't found and\ncreate-new is disabled (match-existing-only mode). Distinct from Matched:\nthese are not imported. Enumerated in DryRunResult.Failures. custom_field\nrows are also Skipped (never Failed) for expected creation blockers —\nbeta disabled, workspace field-slot ceiling reached — since the row's\nown data isn't at fault; those carry DryRunFailureSkippedByPolicy so a\nskip stays identifiable outside match-existing-only mode.", "type": "integer" }, "total": { "type": "integer" }, "updated": { "description": "Updated is rows that matched an existing entity the import then wrote to:\na match-existing-only project whose billable/custom-field values were\napplied, a match-existing-only task whose scalars or custom-field values\nwere applied, an adopted project/task/client (the integration linkage is\nstamped), a re-imported row whose custom-field merge altered the blob, a\nmatched custom field that gained select options, or a rate row whose\ntimeline was rewritten. Disjoint from Matched — a row is never both.\n\nCounts real writes: a value identical to what is already stored leaves the\nrow Matched. The match-existing-only preview diffs the row against the\nentity it matched (task.ImportUpdateWouldChange /\nproject.ImportUpdateWouldChange) and predicts the same way, so re-running\nan already-imported file previews as Matched rather than Updated. It stays\na prediction: a row edited between the preview and the confirm lands on\nwhatever the write's own guard decides.\n\nThe other tiers still predict from whether the row carries anything to\nwrite, so their preview count remains an upper bound: normal-mode custom\nfield merges, matched custom fields gaining options, and the rate tiers,\nwhere the preview reads no timelines at all and reports every surviving\nrate row as a would-create.\n\nAlways serialised (no omitempty), so a response carrying stats always\ncarries this. It is schema-optional only because marking it required would\nbreak every generated client that already builds an EntityStats.", "type": "integer" } } }, "csv.FileInfoResponse": { "type": "object", "required": [ "detected_delimiter", "file_id", "file_name", "headers", "sample_rows" ], "properties": { "detected_delimiter": { "type": "string" }, "file_id": { "type": "integer" }, "file_name": { "type": "string" }, "headers": { "type": "array", "items": { "type": "string" } }, "sample_rows": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "suggested_mappings": { "$ref": "#/definitions/csv.SuggestedMapping" } } }, "csv.FileMapping": { "type": "object", "required": [ "column_mappings", "file_id" ], "properties": { "column_mappings": { "type": "array", "items": { "$ref": "#/definitions/csv.ColumnMapping" } }, "file_id": { "type": "integer" }, "metadata": { "$ref": "#/definitions/csv.MappingMetadata" } } }, "csv.ListProfilesResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/csv.ProfileResponse" } } } }, "csv.MappingMetadata": { "type": "object", "properties": { "date_format": { "type": "string" }, "default_start_time": { "description": "HH:MM. Used when a time_entry start lacks a time component or is\nmissing entirely. Empty falls back to \"09:00\" UTC.", "type": "string" }, "duration_format": { "type": "string" }, "tag_separator": { "type": "string" }, "time_format": { "type": "string" } } }, "csv.MappingRequest": { "type": "object", "required": [ "file_mappings" ], "properties": { "file_mappings": { "type": "array", "items": { "$ref": "#/definitions/csv.FileMapping" } } } }, "csv.MappingResponse": { "type": "object", "required": [ "id", "unmapped_columns", "warnings" ], "properties": { "entity_counts": { "$ref": "#/definitions/csv.EntityCounts" }, "id": { "type": "integer" }, "projected_rows": { "type": "object", "additionalProperties": { "$ref": "#/definitions/csv.ProjectedEntity" } }, "unmapped_columns": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "warnings": { "type": "array", "items": { "$ref": "#/definitions/csv.ValidationError" } } } }, "csv.ProfileResponse": { "type": "object", "required": [ "column_mappings", "created_at", "headers", "id", "name", "updated_at" ], "properties": { "column_mappings": { "type": "array", "items": { "$ref": "#/definitions/csv.ColumnMapping" } }, "created_at": { "type": "string" }, "headers": { "type": "array", "items": { "type": "string" } }, "id": { "type": "integer" }, "metadata": { "$ref": "#/definitions/csv.MappingMetadata" }, "name": { "type": "string" }, "source_product": { "type": "string" }, "updated_at": { "type": "string" } } }, "csv.ProjectedEntity": { "type": "object", "required": [ "fields", "rows", "total" ], "properties": { "fields": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "total": { "type": "integer" } } }, "csv.SuggestedMapping": { "type": "object", "required": [ "column_mappings", "confidence" ], "properties": { "column_mappings": { "type": "array", "items": { "$ref": "#/definitions/csv.ColumnMapping" } }, "confidence": { "type": "number" }, "metadata": { "$ref": "#/definitions/csv.MappingMetadata" } } }, "csv.TargetCustomField": { "type": "object", "required": [ "field", "id", "name", "type" ], "properties": { "field": { "description": "\"cf:\u003cid\u003e\", the ColumnMapping.Field value", "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "description": "text|number|date|checkbox|select|multi_select|users", "type": "string" } } }, "csv.TargetField": { "type": "object", "required": [ "name", "required", "type" ], "properties": { "description": { "type": "string" }, "is_list": { "type": "boolean" }, "name": { "type": "string" }, "required": { "type": "boolean" }, "type": { "type": "string" } } }, "csv.TargetRelationship": { "type": "object", "required": [ "field", "resolve_by", "target_entity" ], "properties": { "field": { "type": "string" }, "is_list": { "type": "boolean" }, "is_scope": { "type": "boolean" }, "resolve_by": { "type": "array", "items": { "type": "string" } }, "target_entity": { "type": "string" } } }, "csv.TargetSchema": { "type": "object", "required": [ "entity", "fields" ], "properties": { "custom_fields": { "description": "CustomFields is the per-workspace list of importable custom field\ntargets. Populated only in API responses; empty in the static registry.", "type": "array", "items": { "$ref": "#/definitions/csv.TargetCustomField" } }, "entity": { "type": "string" }, "fields": { "type": "array", "items": { "$ref": "#/definitions/csv.TargetField" } }, "relationships": { "type": "array", "items": { "$ref": "#/definitions/csv.TargetRelationship" } } } }, "csv.UpdateProfileRequest": { "type": "object", "properties": { "column_mappings": { "type": "array", "items": { "$ref": "#/definitions/csv.ColumnMapping" } }, "headers": { "type": "array", "items": { "type": "string" } }, "metadata": { "$ref": "#/definitions/csv.MappingMetadata" }, "name": { "type": "string" }, "source_product": { "type": "string" } } }, "csv.UploadRequestResponse": { "type": "object", "required": [ "created_at", "dry_run_progress", "dry_run_result", "dry_run_stale", "dry_run_status", "files", "id", "progress", "send_invites", "stats", "status", "updated_at", "user_id", "warnings", "workspace_id" ], "properties": { "can_invite_members": { "description": "CanInviteMembers mirrors the field on UploadResponse so a resumed or\nreloaded wizard can re-derive it — the FE store is in-memory, so without\nthis the warning silently disappears on refresh and the admin confirms\ninto the failed rows it exists to prevent. Resolved for the user making\n*this* request, not the one who uploaded.\n\nNil means \"not computed\": the list endpoint shares this struct and\nanswering it per row would cost one authz call each. Treat nil as unknown\nrather than as false.", "type": "boolean" }, "created_at": { "type": "string" }, "dry_run_progress": { "type": "integer" }, "dry_run_result": { "$ref": "#/definitions/csv.DryRunResult" }, "dry_run_stale": { "type": "boolean" }, "dry_run_status": { "description": "Dry-run state. DryRunStatus is \"\" until the first dry-run runs.\nDryRunStale is true when a completed result was computed against a mapping\nthat has since changed — the FE should re-run before showing the confirm\nsummary.", "type": "string" }, "files": { "type": "array", "items": { "$ref": "#/definitions/csv.FileInfoResponse" } }, "id": { "type": "integer" }, "import_job_id": { "type": "string" }, "progress": { "type": "integer" }, "send_invites": { "type": "boolean" }, "stats": { "$ref": "#/definitions/csv.EntityCounts" }, "status": { "type": "string" }, "unsettable_fields": { "description": "UnsettableFields mirrors the field on UploadResponse so a resumed wizard\nre-derives it for the user making *this* request. Nil means not computed\n(the list endpoint shares this struct); treat that as unknown, not as\n\"everything is settable\".", "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "string" }, "user_id": { "type": "integer" }, "warnings": { "type": "array", "items": { "type": "string" } }, "workspace_id": { "type": "integer" } } }, "csv.UploadResponse": { "type": "object", "required": [ "available_targets", "can_invite_members", "files", "id", "unsettable_fields", "warnings" ], "properties": { "available_targets": { "type": "array", "items": { "$ref": "#/definitions/csv.TargetSchema" } }, "can_invite_members": { "description": "CanInviteMembers reports whether this admin may add people who are not\nalready in the organization. False means the import can still update\nmembers it matches, but every new email would be rejected — so the UI\nshould say so while the mapping is still being built, rather than letting\nthe admin discover it from a page of failed rows after confirming.", "type": "boolean" }, "entity_counts": { "$ref": "#/definitions/csv.EntityCounts" }, "files": { "type": "array", "items": { "$ref": "#/definitions/csv.FileInfoResponse" } }, "id": { "type": "integer" }, "unsettable_fields": { "description": "UnsettableFields names the qualified targets (\"user.rate\") this admin\nlacks the permission to write, so the mapping screen can disable them with\na reason instead of accepting a column that the import then drops.\n\nA list rather than a flag per field: the set grows with every\npermission-gated attribute, and a caller that does not recognise an entry\ncan ignore it. CanInviteMembers stays separate because it is not a field —\nit decides whether members can be created at all, which is the mode\ntoggle, not a column.\n\nEmpty means everything mappable is settable, which is the common case.", "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "csv.UploadWorkflowAck": { "type": "object", "required": [ "request_id" ], "properties": { "request_id": { "type": "integer" } } }, "csv.ValidationError": { "type": "object", "required": [ "message", "row" ], "properties": { "column": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" }, "row": { "type": "integer" }, "value": { "type": "string" } } }, "customfield.CreateOptionPayload": { "type": "object", "required": [ "name" ], "properties": { "color": { "type": "string" }, "description": { "type": "string" }, "name": { "type": "string" } } }, "customfield.CreatePayload": { "type": "object", "required": [ "entity_type", "field_type", "name" ], "properties": { "description": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "project", "task", "user" ] }, "field_type": { "type": "string", "enum": [ "select", "multi_select", "text", "number", "date", "checkbox", "users" ] }, "name": { "type": "string" }, "options": { "type": "array", "maxItems": 100, "items": { "$ref": "#/definitions/customfield.CreateOptionPayload" } } } }, "customfield.ReorderOptionsPayload": { "type": "object", "required": [ "ordered_ids" ], "properties": { "ordered_ids": { "description": "max=100 mirrors the per-field option cap. ordered_ids may list a subset of the\nactive options (the rest keep their current order), so unlike field reorder it\nisn't coupled to a full active set.", "type": "array", "maxItems": 100, "minItems": 1, "uniqueItems": true, "items": { "type": "integer" } } } }, "customfield.ReorderPayload": { "type": "object", "required": [ "entity_type", "ordered_ids" ], "properties": { "entity_type": { "type": "string", "enum": [ "project", "task", "user" ] }, "ordered_ids": { "description": "max=50 must stay in sync with constants.MaxCFSlots: ordered_ids carries\nthe full active set, which create caps at MaxCFSlots per entity_type, so a\nlower bound here would make full workspaces un-reorderable. Struct tags\ncan't reference Go constants; TestReorderPayloadCapMatchesMaxCFSlots guards\nthe coupling.", "type": "array", "maxItems": 50, "minItems": 1, "uniqueItems": true, "items": { "type": "integer" } } } }, "customfield.UpdateOptionPayload": { "type": "object", "required": [ "name" ], "properties": { "color": { "type": "string" }, "description": { "type": "string" }, "name": { "type": "string" } } }, "customfield.UpdatePayload": { "type": "object", "required": [ "name" ], "properties": { "description": { "type": "string" }, "name": { "type": "string" } } }, "datagenerator.Payload": { "type": "object", "required": [ "end_date", "max_time_blocks_per_task", "max_time_entries_per_task", "min_time_blocks_per_task", "min_time_entries_per_task", "number_of_clients", "number_of_projects", "number_of_tasks", "private", "start_date" ], "properties": { "end_date": { "type": "string" }, "max_time_blocks_per_task": { "type": "integer" }, "max_time_entries_per_task": { "type": "integer" }, "min_time_blocks_per_task": { "type": "integer" }, "min_time_entries_per_task": { "type": "integer" }, "number_of_clients": { "type": "integer" }, "number_of_projects": { "type": "integer" }, "number_of_tasks": { "type": "integer" }, "private": { "description": "Sets the generated tasks, and projects visibility", "type": "boolean" }, "start_date": { "type": "string" } } }, "dictionary.BasicDict": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "dictionary.BasicDictionary": { "type": "object", "additionalProperties": { "$ref": "#/definitions/dictionary.BasicDict" } }, "dictionary.ClientDictionary": { "type": "object", "additionalProperties": { "$ref": "#/definitions/dictionary.BasicDict" } }, "dictionary.CustomFieldDict": { "type": "object", "required": [ "field_type", "name" ], "properties": { "field_type": { "type": "string" }, "name": { "type": "string" } } }, "dictionary.CustomFieldOptionDict": { "type": "object", "required": [ "custom_field_id", "is_deleted", "name" ], "properties": { "custom_field_id": { "type": "integer" }, "is_deleted": { "type": "boolean" }, "name": { "type": "string" } } }, "dictionary.CustomFieldOptionsDictionary": { "type": "object", "additionalProperties": { "$ref": "#/definitions/dictionary.CustomFieldOptionDict" } }, "dictionary.CustomFieldsDictionary": { "type": "object", "additionalProperties": { "$ref": "#/definitions/dictionary.CustomFieldDict" } }, "dictionary.Dictionary": { "type": "object", "properties": { "clients": { "$ref": "#/definitions/dictionary.ClientDictionary" }, "custom_field_options": { "$ref": "#/definitions/dictionary.CustomFieldOptionsDictionary" }, "custom_fields": { "$ref": "#/definitions/dictionary.CustomFieldsDictionary" }, "groups": { "$ref": "#/definitions/dictionary.BasicDictionary" }, "projects": { "$ref": "#/definitions/dictionary.ProjectDictionary" }, "status": { "$ref": "#/definitions/dictionary.StatusDictionary" }, "tags": { "$ref": "#/definitions/dictionary.TagDictionary" }, "tasks": { "$ref": "#/definitions/dictionary.TaskDictionary" }, "user_tags": { "$ref": "#/definitions/dictionary.TagDictionary" }, "users": { "$ref": "#/definitions/dictionary.UserDictionary" } } }, "dictionary.ProjectDict": { "type": "object", "required": [ "auto_compute_estimates", "billable", "children_count", "id", "is_recurring", "name", "task_ids" ], "properties": { "auto_compute_estimates": { "type": "boolean" }, "billable": { "type": "boolean" }, "children_count": { "type": "integer" }, "client_id": { "type": "integer" }, "color": { "type": "string" }, "completed_at": { "type": "string", "format": "date-time" }, "custom_field_values": { "type": "array", "items": { "$ref": "#/definitions/models.CustomFieldValue" } }, "end_date": { "type": "string", "format": "date" }, "estimated_mins": { "type": "integer" }, "fixed_fee": { "$ref": "#/definitions/dictionary.ProjectFixedFee" }, "id": { "type": "integer" }, "is_recurring": { "type": "boolean" }, "name": { "type": "string" }, "parent_id": { "type": "integer" }, "recurring_project_id": { "type": "integer" }, "rollover_mins": { "type": "integer", "x-nullable": true }, "source_template_id": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "task_ids": { "type": "array", "items": { "type": "integer" } } } }, "dictionary.ProjectDictionary": { "type": "object", "additionalProperties": { "$ref": "#/definitions/dictionary.ProjectDict" } }, "dictionary.ProjectFixedFee": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number" }, "currency": { "type": "string" } } }, "dictionary.StatusDict": { "type": "object", "required": [ "id", "name", "position", "type" ], "properties": { "emoji": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "position": { "type": "integer" }, "type": { "$ref": "#/definitions/models.StatusType" } } }, "dictionary.StatusDictionary": { "type": "object", "additionalProperties": { "$ref": "#/definitions/dictionary.StatusDict" } }, "dictionary.TagDict": { "type": "object", "required": [ "id", "name" ], "properties": { "color": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } } }, "dictionary.TagDictionary": { "type": "object", "additionalProperties": { "$ref": "#/definitions/dictionary.TagDict" } }, "dictionary.TaskDict": { "type": "object", "required": [ "children_count", "creator_id", "id", "name", "pinned", "priority", "private", "status_id", "tag_ids" ], "properties": { "billable": { "type": "boolean" }, "children_count": { "type": "integer" }, "color": { "type": "string" }, "creator_id": { "type": "integer" }, "custom_field_values": { "type": "array", "items": { "$ref": "#/definitions/models.CustomFieldValue" } }, "description": { "type": "string" }, "estimated_mins": { "type": "integer" }, "id": { "type": "integer" }, "name": { "type": "string" }, "notes": { "type": "string" }, "parent_task_id": { "type": "integer" }, "pinned": { "type": "boolean" }, "priority": { "type": "string" }, "private": { "type": "boolean" }, "project_id": { "type": "integer" }, "status_id": { "type": "integer" }, "status_updated_at": { "type": "string" }, "tag_ids": { "type": "array", "items": { "type": "integer" } } } }, "dictionary.TaskDictionary": { "type": "object", "additionalProperties": { "$ref": "#/definitions/dictionary.TaskDict" } }, "dictionary.UserDict": { "type": "object", "required": [ "email", "id", "name" ], "properties": { "email": { "type": "string" }, "group_ids": { "type": "array", "items": { "type": "integer" } }, "id": { "type": "integer" }, "name": { "type": "string" }, "organization_user_id": { "type": "integer" }, "weekly_working_hours": { "type": "number" } } }, "dictionary.UserDictionary": { "type": "object", "additionalProperties": { "$ref": "#/definitions/dictionary.UserDict" } }, "dto.AggregationFilterRequest": { "type": "object", "required": [ "aggregation", "conditions", "operator", "property", "value" ], "properties": { "aggregation": { "$ref": "#/definitions/dto.AggregationRequest" }, "conditions": { "$ref": "#/definitions/dto.AggregationsFilterRequest" }, "operator": { "type": "string" }, "property": { "type": "string" }, "value": {} } }, "dto.AggregationRequest": { "type": "object", "required": [ "function", "property" ], "properties": { "function": { "type": "string" }, "property": { "type": "string" } } }, "dto.AggregationsFilterRequest": { "type": "array", "items": { "$ref": "#/definitions/dto.AggregationFilterRequest" } }, "dto.AttributeRequest": { "type": "object", "required": [ "property" ], "properties": { "property": { "type": "string" } } }, "dto.FilterRequest": { "type": "object", "required": [ "conditions", "operator", "property", "value" ], "properties": { "conditions": { "type": "array", "items": { "$ref": "#/definitions/dto.FilterRequest" } }, "operator": { "type": "string" }, "property": { "type": "string" }, "value": {} } }, "dto.GroupingRequest": { "type": "object", "required": [ "property", "show_empty" ], "properties": { "property": { "type": "string" }, "show_empty": { "type": "boolean" } } }, "dto.ModifiersRequest": { "type": "object", "additionalProperties": {} }, "dto.OrdinationRequest": { "type": "object", "required": [ "direction", "nulls", "property" ], "properties": { "direction": { "type": "string" }, "nulls": { "type": "string" }, "property": { "type": "string" } } }, "dto.PaginationRequest": { "type": "object", "required": [ "page", "per_page" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "dto.PeriodRequest": { "type": "object", "required": [ "from", "preset", "to" ], "properties": { "from": { "type": "string" }, "preset": { "type": "string" }, "to": { "type": "string" } } }, "dto.QueryRequest": { "type": "object", "required": [ "aggregation_filters", "aggregations", "attributes", "conversion_date", "currency", "filters", "groupings", "limit", "modifiers", "ordinations", "pagination", "period", "transformations" ], "properties": { "aggregation_filters": { "type": "array", "items": { "$ref": "#/definitions/dto.AggregationFilterRequest" } }, "aggregations": { "type": "array", "items": { "$ref": "#/definitions/dto.AggregationRequest" } }, "attributes": { "type": "array", "items": { "$ref": "#/definitions/dto.AttributeRequest" } }, "conversion_date": { "description": "ConversionDate is the profitability report's optional \"as of\" date: every converted\nvalue is looked up at this one date instead of each row's own business/fee date.\nOptional — omitted means each row uses its own date. Applies to actuals and fixed\nfees; the forecast always converts at today. A date past our latest published rate\nfalls back to that latest rate (no error). Has no effect unless the request selects a\nconverted property (converted_revenue / converted_labor_cost).", "allOf": [ { "$ref": "#/definitions/models.DateOnly" } ] }, "currency": { "description": "Currency is the profitability report's FX-conversion target (ISO 4217). Optional:\nwhen omitted, the converted properties target the workspace's configured currency.\nMalformed input is a 400. Has no effect unless the request selects a converted\nproperty (converted_revenue / converted_labor_cost).", "type": "string" }, "filters": { "type": "array", "items": { "$ref": "#/definitions/dto.FilterRequest" } }, "groupings": { "type": "array", "items": { "$ref": "#/definitions/dto.GroupingRequest" } }, "limit": { "type": "integer" }, "modifiers": { "$ref": "#/definitions/dto.ModifiersRequest" }, "ordinations": { "type": "array", "items": { "$ref": "#/definitions/dto.OrdinationRequest" } }, "pagination": { "$ref": "#/definitions/dto.PaginationRequest" }, "period": { "$ref": "#/definitions/dto.PeriodRequest" }, "transformations": { "type": "array", "items": { "$ref": "#/definitions/dto.TransformationRequest" } } } }, "dto.TransformationRequest": { "type": "object", "required": [ "name", "parameters" ], "properties": { "name": { "type": "string" }, "parameters": { "type": "array", "items": {} } } }, "events.PlatformOrigin": { "type": "string", "enum": [ "web", "mobile", "desktop", "extension" ], "x-enum-varnames": [ "PlatformOriginWeb", "PlatformOriginMobile", "PlatformOriginDesktop", "PlatformOriginBrowserExtension" ] }, "extensionintegration.CreatePayload": { "type": "object", "required": [ "definition", "id", "name" ], "properties": { "definition": { "type": "object" }, "id": { "type": "string" }, "name": { "type": "string" } } }, "extensionintegration.UpsertPayload": { "type": "object", "required": [ "definition", "name" ], "properties": { "definition": { "type": "object" }, "name": { "type": "string" } } }, "extensiontracking.StartFromDescriptionPayload": { "type": "object", "required": [ "extension_source", "name", "type" ], "properties": { "billable": { "type": "boolean" }, "create_project_if_not_found": { "type": "boolean" }, "create_tags_if_not_found": { "type": "boolean" }, "create_task_if_not_found": { "type": "boolean" }, "custom_fields": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" }, "estimated_mins": { "type": "integer", "minimum": 0 }, "extension_source": { "type": "string" }, "extension_url": { "type": "string" }, "name": { "type": "string" }, "notes": { "type": "string" }, "private": { "type": "boolean" }, "project_name": { "type": "string" }, "resolution_strategy": { "type": "string", "enum": [ "uri", "name", "name_project", "name_project_tags" ] }, "start": { "type": "string", "format": "date-time" }, "tag_names": { "type": "array", "items": { "type": "string" } }, "type": { "$ref": "#/definitions/models.TimeEntryType" } } }, "extensiontracking.StartFromDescriptionResult": { "type": "object", "required": [ "match_reason", "project_created", "project_resolved", "resolution_strategy", "tags_created", "tags_not_found", "task", "task_created", "time_entry" ], "properties": { "match_reason": { "type": "string" }, "project_created": { "type": "boolean" }, "project_resolved": { "type": "boolean" }, "resolution_strategy": { "type": "string" }, "tags_created": { "type": "array", "items": { "type": "string" } }, "tags_not_found": { "type": "array", "items": { "type": "string" } }, "task": { "$ref": "#/definitions/models.Task" }, "task_created": { "type": "boolean" }, "time_entry": { "$ref": "#/definitions/models.TimeEntry" } } }, "flexq.EnrichedResult": { "type": "object", "required": [ "data_hierarchical", "data_json_row", "data_table", "dictionaries" ], "properties": { "data_hierarchical": { "type": "object", "additionalProperties": {} }, "data_json_row": { "type": "array", "items": { "$ref": "#/definitions/model.Result" } }, "data_table": {}, "dictionaries": { "$ref": "#/definitions/dictionary.Dictionary" }, "total_count": { "type": "integer" } } }, "goal.CreatePayload": { "type": "object", "required": [ "billable", "comparison", "end_date", "icon", "monthly_anchor", "name", "project_ids", "recurrence", "start_date", "tag_ids", "target_seconds", "task_ids", "weekdays" ], "properties": { "billable": { "type": "boolean" }, "client_ids": { "type": "array", "items": { "type": "integer" } }, "comparison": { "type": "string", "enum": [ "more_than", "less_than" ] }, "description": { "type": "string" }, "end_date": { "type": "string", "format": "date" }, "icon": { "type": "string" }, "monthly_anchor": { "type": "string", "enum": [ "calendar", "first_workday" ] }, "name": { "type": "string" }, "project_ids": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": "string", "enum": [ "daily", "weekly", "daily_workdays", "monthly" ] }, "start_date": { "type": "string", "format": "date" }, "tag_ids": { "type": "array", "items": { "type": "integer" } }, "target_seconds": { "type": "integer" }, "task_ids": { "type": "array", "items": { "type": "integer" } }, "weekdays": { "type": "array", "items": { "type": "integer" } } } }, "goal.ReorderPayload": { "type": "object", "required": [ "goal_ids" ], "properties": { "goal_ids": { "type": "array", "items": { "type": "integer" } } } }, "goal.UpdatePayload": { "type": "object", "properties": { "active": { "type": "boolean" }, "comparison": { "type": "string" }, "description": { "type": "string", "x-nullable": true }, "end_date": { "type": "string", "format": "date", "x-nullable": true }, "icon": { "type": "string" }, "name": { "type": "string" }, "target_seconds": { "type": "integer" } } }, "importer.ImportJob": { "type": "object", "required": [ "created_at", "failed_activities", "import_scope", "job_id", "progress", "source_product_id", "source_workspace_id", "updated_at", "user_id", "workspace_id" ], "properties": { "created_at": { "type": "string" }, "failed_activities": { "type": "array", "items": { "type": "string" } }, "import_scope": { "type": "string" }, "job_id": { "type": "string" }, "progress": { "type": "integer" }, "progress_details": { "$ref": "#/definitions/importer.ImportProgressDetails" }, "result_summary": { "$ref": "#/definitions/importer.ImportResultSummary" }, "source_product_id": { "type": "integer" }, "source_workspace_id": { "type": "integer" }, "status": { "type": "string" }, "updated_at": { "type": "string" }, "user_id": { "type": "integer" }, "workspace_id": { "type": "integer" } } }, "importer.ImportJobResponse": { "type": "object", "required": [ "created_at", "import_scope", "job_id", "progress", "source_product_id", "source_workspace_id", "status" ], "properties": { "created_at": { "type": "string" }, "import_scope": { "type": "string" }, "job_id": { "type": "string" }, "progress": { "type": "integer" }, "progress_details": { "$ref": "#/definitions/importer.ImportProgressDetails" }, "result_summary": { "$ref": "#/definitions/importer.ImportResultSummary" }, "source_product_id": { "type": "integer" }, "source_workspace_id": { "type": "integer" }, "status": { "type": "string" } } }, "importer.ImportProgressDetails": { "type": "object", "required": [ "stages" ], "properties": { "current_stage": { "$ref": "#/definitions/importer.ImportProgressStage" }, "stages": { "type": "array", "items": { "$ref": "#/definitions/importer.ImportProgressStage" } } } }, "importer.ImportProgressStage": { "type": "object", "required": [ "code", "index", "status", "total" ], "properties": { "code": { "type": "string" }, "index": { "type": "integer" }, "status": { "type": "string" }, "total": { "type": "integer" } } }, "importer.ImportResultSummary": { "type": "object", "required": [ "clients", "members", "projects", "tasks", "time_entries" ], "properties": { "clients": { "type": "integer" }, "members": { "type": "integer" }, "projects": { "type": "integer" }, "rates": { "type": "integer" }, "tasks": { "type": "integer" }, "time_entries": { "type": "integer" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "importer.importPreview": { "type": "object", "required": [ "mappings", "member_sections", "members", "summary" ], "properties": { "mappings": { "type": "array", "items": { "$ref": "#/definitions/importer.importPreviewMapping" } }, "member_sections": { "$ref": "#/definitions/importer.importPreviewMemberSections" }, "members": { "type": "array", "items": { "$ref": "#/definitions/importer.member" } }, "summary": { "$ref": "#/definitions/importer.importPreviewSummary" }, "warnings": { "type": "array", "items": { "$ref": "#/definitions/importer.importPreviewWarning" } } } }, "importer.importPreviewDetailPage": { "type": "object", "required": [ "data", "page", "per_page" ], "properties": { "data": { "description": "No total is returned because time-entry totals require scanning the same Track reports data that pagination is meant to avoid.", "type": "array", "items": { "$ref": "#/definitions/importer.importPreviewDetailRow" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "importer.importPreviewDetailRow": { "type": "object", "properties": { "active": { "type": "boolean" }, "archived": { "type": "boolean" }, "billable": { "type": "boolean" }, "client_id": { "type": "integer" }, "client_name": { "type": "string" }, "color": { "type": "string" }, "description": { "type": "string" }, "duration_seconds": { "type": "integer" }, "email": { "type": "string" }, "estimated_seconds": { "type": "integer" }, "name": { "type": "string" }, "pinned": { "type": "boolean" }, "present": { "type": "boolean" }, "private": { "type": "boolean" }, "project_id": { "type": "integer" }, "project_name": { "type": "string" }, "role": { "type": "string" }, "source_id": { "type": "string" }, "start": { "type": "string" }, "stop": { "type": "string" }, "task_id": { "type": "integer" }, "task_name": { "type": "string" } } }, "importer.importPreviewMapping": { "type": "object", "required": [ "focus_entity", "source_entity" ], "properties": { "description": { "type": "string" }, "focus_entity": { "type": "string" }, "source_entity": { "type": "string" } } }, "importer.importPreviewMemberSection": { "type": "object", "required": [ "count", "included_in_import", "members", "selected_by_default" ], "properties": { "count": { "type": "integer" }, "description": { "type": "string" }, "included_in_import": { "type": "boolean" }, "members": { "type": "array", "items": { "$ref": "#/definitions/importer.member" } }, "selected_by_default": { "type": "boolean" } } }, "importer.importPreviewMemberSections": { "type": "object", "required": [ "active", "deactivated" ], "properties": { "active": { "$ref": "#/definitions/importer.importPreviewMemberSection" }, "deactivated": { "$ref": "#/definitions/importer.importPreviewMemberSection" } } }, "importer.importPreviewSummary": { "type": "object", "required": [ "clients", "members", "projects", "tasks", "time_entries" ], "properties": { "clients": { "$ref": "#/definitions/importer.importPreviewSummaryCount" }, "members": { "$ref": "#/definitions/importer.importPreviewSummaryCount" }, "projects": { "$ref": "#/definitions/importer.importPreviewSummaryCount" }, "tasks": { "$ref": "#/definitions/importer.importPreviewSummaryCount" }, "time_entries": { "$ref": "#/definitions/importer.importPreviewSummaryCount" } } }, "importer.importPreviewSummaryCount": { "type": "object", "required": [ "approximate", "value" ], "properties": { "approximate": { "type": "boolean" }, "value": { "type": "integer" } } }, "importer.importPreviewWarning": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "importer.importRequest": { "type": "object", "required": [ "import_scope", "source_product_id", "source_workspace_id" ], "properties": { "active_only": { "type": "boolean", "example": true }, "import_scope": { "type": "string", "enum": [ "full_workspace", "user_only" ], "example": "user_only" }, "skip_user_import": { "type": "boolean", "example": false }, "source_product_id": { "type": "integer", "example": 1 }, "source_workspace_id": { "type": "integer", "example": 623123 }, "time_entries_end": { "type": "string", "example": "2026-04-14" }, "time_entries_start": { "type": "string", "example": "2026-03-31" } } }, "importer.member": { "type": "object", "required": [ "active", "email", "focus_role_id", "granted_focus_role_id", "name", "plan_role", "present", "track_role" ], "properties": { "active": { "type": "boolean" }, "email": { "type": "string" }, "focus_role_id": { "type": "integer" }, "granted_focus_role_id": { "type": "integer" }, "name": { "type": "string" }, "plan_role": { "type": "string" }, "present": { "type": "boolean" }, "track_role": { "type": "string" } } }, "importer.source": { "type": "object", "required": [ "admin", "entities", "organization_id", "product_id", "product_name", "workspace_id", "workspace_name" ], "properties": { "admin": { "type": "boolean" }, "entities": { "type": "array", "items": { "type": "string" } }, "organization_id": { "type": "integer" }, "product_id": { "type": "integer" }, "product_name": { "type": "string" }, "workspace_id": { "type": "integer" }, "workspace_name": { "type": "string" } } }, "mapping.Rule": { "type": "object", "required": [ "created_at", "id", "project_id", "task_id", "title", "updated_at" ], "properties": { "created_at": { "type": "string" }, "id": { "type": "integer" }, "project_id": { "type": "integer", "x-nullable": true }, "task_id": { "type": "integer", "x-nullable": true }, "title": { "type": "string" }, "updated_at": { "type": "string" } } }, "mcp.ContextResponse": { "type": "object", "required": [ "organization_id", "workspace_id" ], "properties": { "organization_id": { "type": "integer" }, "workspace_id": { "type": "integer" } } }, "milestone.PartialUpdatePayload": { "type": "object", "properties": { "color": { "description": "nolint:lll", "type": "string", "x-nullable": true }, "completed_at": { "description": "nolint:lll", "type": "string", "format": "date-time", "x-nullable": true }, "due_date": { "description": "nolint:lll", "type": "string", "format": "date" }, "name": { "description": "nolint:lll", "type": "string" }, "project_ids": { "description": "nolint:lll", "type": "array", "items": { "type": "integer" } }, "team_ids": { "description": "nolint:lll", "type": "array", "items": { "type": "integer" } } } }, "milestone.Payload": { "type": "object", "required": [ "color", "due_date", "name" ], "properties": { "color": { "type": "string" }, "completed_at": { "description": "nolint:lll", "type": "string", "format": "date-time" }, "due_date": { "description": "nolint:lll", "type": "string", "format": "date" }, "name": { "type": "string" }, "project_ids": { "type": "array", "items": { "type": "integer" } }, "team_ids": { "type": "array", "items": { "type": "integer" } } } }, "model.Result": { "type": "object", "additionalProperties": {} }, "models.BillableSource": { "type": "string", "enum": [ "manual", "task_default" ], "x-enum-varnames": [ "BillableSourceManual", "BillableSourceTaskDefault" ] }, "models.Calendar": { "type": "object", "required": [ "auto_track", "background_color", "calendar_id", "calendar_integration_id", "created_at", "default_action", "default_planned_task_id", "default_project_id", "default_workspace_id", "deleted_at", "external_id", "focus_auto_track", "foreground_color", "name", "remind_tracking", "selected", "updated_at" ], "properties": { "auto_track": { "type": "boolean" }, "background_color": { "type": "string" }, "calendar_id": { "type": "integer" }, "calendar_integration_id": { "type": "integer" }, "created_at": { "type": "string" }, "default_action": { "type": "string" }, "default_planned_task_id": { "type": "integer" }, "default_project_id": { "type": "integer" }, "default_workspace_id": { "type": "integer" }, "deleted_at": { "type": "string" }, "external_id": { "type": "string" }, "focus_auto_track": { "type": "boolean" }, "foreground_color": { "type": "string" }, "name": { "type": "string" }, "remind_tracking": { "description": "The following fields are deprecated but we need to keep them for backward compatibility with previous versions\nof mobile apps", "type": "boolean" }, "selected": { "type": "boolean" }, "updated_at": { "type": "string" } } }, "models.Client": { "type": "object", "required": [ "active", "created_at", "id", "name", "workspace_id" ], "properties": { "active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "deleted_at": { "type": "string", "format": "date-time" }, "id": { "type": "integer" }, "name": { "type": "string" }, "toggl_user_id": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "models.ClientLite": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "models.Computation": { "type": "object", "required": [ "assigned_tasks_count", "date", "estimated_minutes", "estimated_remaining_minutes", "time_off_minutes", "working_minutes" ], "properties": { "assigned_tasks_count": { "description": "Number of tasks assigned to the user on the specified `Date`", "type": "integer" }, "date": { "description": "The date of the computation", "type": "string", "format": "date" }, "estimated_minutes": { "description": "The summation of a user's tasks' estimated minutes in the day", "type": "integer" }, "estimated_remaining_minutes": { "description": "EstimatedRemainingMinutes is unfinished scheduled work placed from workspace-local today.", "type": "integer" }, "time_off_minutes": { "description": "TimeOffMinutes is the PTO overlap deducted from WorkingMinutes.", "type": "integer" }, "working_minutes": { "description": "The user's per day working minutes set in their user preferences", "type": "integer" } } }, "models.ComputationGroup": { "type": "object", "required": [ "computations", "id", "type" ], "properties": { "computations": { "description": "The computations that belong to the grouping entity", "type": "array", "items": { "$ref": "#/definitions/models.Computation" } }, "id": { "description": "The ID of the entity that groups the computations", "type": "integer" }, "type": { "description": "The type of the entity that groups the computations", "type": "string", "enum": [ "user" ] } } }, "models.CustomFieldOption": { "type": "object", "required": [ "created_at", "custom_field_id", "id", "name", "position", "updated_at", "workspace_id" ], "properties": { "color": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "custom_field_id": { "type": "integer" }, "deleted_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "position": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "models.CustomFieldOptionValue": { "type": "object", "required": [ "is_deleted", "option_id", "option_name" ], "properties": { "is_deleted": { "type": "boolean" }, "option_id": { "type": "integer" }, "option_name": { "type": "string" } } }, "models.CustomFieldValue": { "type": "object", "required": [ "custom_field_id", "custom_field_name", "field_type", "selected_options", "value" ], "properties": { "custom_field_id": { "type": "integer" }, "custom_field_name": { "type": "string" }, "field_type": { "type": "string" }, "selected_options": { "type": "array", "items": { "$ref": "#/definitions/models.CustomFieldOptionValue" } }, "value": {} } }, "models.CustomFieldWithOptions": { "type": "object", "required": [ "created_at", "entity_type", "field_type", "id", "name", "options", "position", "status", "total_options", "updated_at", "workspace_id" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "entity_type": { "type": "string" }, "field_type": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "options": { "type": "array", "items": { "$ref": "#/definitions/models.CustomFieldOption" } }, "position": { "type": "integer" }, "status": { "type": "string" }, "total_options": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "models.CustomerResponse": { "type": "object", "required": [ "id", "url" ], "properties": { "id": { "type": "string" }, "url": { "type": "string" } } }, "models.DateOnly": { "type": "object" }, "models.EffectiveProjectRatesSummary": { "type": "object", "required": [ "billable", "currency", "end_at", "has_more_rates", "hourly_rate", "project_color", "project_created_at", "project_id", "project_name", "project_rate_id", "start_at", "workspace_rate_id" ], "properties": { "billable": { "type": "boolean" }, "currency": { "type": "string" }, "end_at": { "type": "string" }, "has_more_rates": { "type": "boolean" }, "hourly_rate": { "type": "number" }, "project_color": { "type": "string" }, "project_created_at": { "type": "string" }, "project_id": { "type": "integer" }, "project_name": { "type": "string" }, "project_rate_id": { "type": "integer" }, "start_at": { "type": "string" }, "workspace_rate_id": { "type": "integer" } } }, "models.EnrichedTaskGroupEntry": { "type": "object", "required": [ "allocation_unit", "end_date", "estimate_type", "id", "name", "private", "source", "start_date", "status_id" ], "properties": { "allocation_unit": { "description": "How the task's estimate allocations express their value.", "type": "string", "enum": [ "percent", "flat" ] }, "assignee_user_ids": { "type": "array", "items": { "type": "integer" } }, "assignees": { "description": "Assignees is the read-only unified user/team assignment list, only\npopulated when include_assignees is requested. Mirrors the task endpoint.", "type": "array", "items": { "$ref": "#/definitions/models.TaskAssignment" } }, "client": { "$ref": "#/definitions/models.ClientLite" }, "color": { "type": "string" }, "created_at": { "description": "CreatedAt is omitted for virtual entries.", "type": "string" }, "end_date": { "description": "When a task ends", "type": "string" }, "estimate_type": { "description": "Type of EstimatedMins. Total is spread throughout the task date range, and\ndaily is a per day estimate.", "type": "string", "enum": [ "daily", "total" ] }, "estimated_mins": { "description": "Estimated minutes of the task", "type": "integer" }, "id": { "description": "The task's ID", "type": "integer" }, "masked": { "description": "Masked indicates the task belongs to a private project the user doesn't have access to.\nWhen true, sensitive fields (Name, Client) are nulled.", "type": "boolean" }, "name": { "description": "Name of the task", "type": "string" }, "parent_task": { "$ref": "#/definitions/models.TaskLite" }, "period_end": { "description": "PeriodEnd is the recurring project period's last day.", "type": "string", "format": "date" }, "period_start": { "description": "PeriodStart is the recurring project period's first day.", "type": "string", "format": "date" }, "private": { "type": "boolean" }, "project": { "$ref": "#/definitions/models.ProjectLite" }, "project_id": { "description": "Project ID fo the task", "type": "integer" }, "projection_revision": { "description": "ProjectionRevision identifies the projected period version.", "type": "string" }, "source": { "type": "string" }, "source_template_task_id": { "description": "SourceTemplateTaskID identifies the task template used for this entry.", "type": "integer" }, "start_date": { "description": "When a task starts", "type": "string" }, "status_id": { "description": "Status ID of the task", "type": "integer" }, "template_project_id": { "description": "TemplateProjectID identifies the recurring project template.", "type": "integer" }, "virtual": { "description": "Virtual indicates the entry is an unmaterialized recurring task.", "type": "boolean" }, "weight": { "description": "The weight of a task in the timeline. This is not unique, and one or more\ntasks may have the same weight as long as their dates do not conflict.", "type": "integer" } } }, "models.ExtensionIntegration": { "type": "object", "required": [ "created_at", "definition", "id", "name", "organization_id", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "definition": { "type": "object" }, "deleted_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_id": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } }, "models.Goal": { "type": "object", "required": [ "active", "best_streak", "billable", "client_ids", "comparison", "created_at", "current_recurrence", "deleted_at", "end_date", "goal_id", "icon", "is_syncing", "last_completed_recurrence_end_date", "last_notified_at", "monthly_anchor", "name", "periods_met", "periods_total", "permissions", "position", "previous_streak", "project_ids", "recurrence", "start_date", "status", "streak", "streak_consolidated_at", "synced_at", "tag_ids", "target_seconds", "task_ids", "toggl_user_id", "updated_at", "weekdays", "workspace_id" ], "properties": { "active": { "type": "boolean" }, "best_streak": { "description": "BestStreak (db column best_streak) is the durable peak streak length ever reached,\nfolded in at consolidation time from bestStreakInWindow's scan of the loaded warehouse\nwindow (see models.go). It is monotonic (persisted via GREATEST), so it survives a\nbroken chain that resets PreviousStreak/Streak -- unlike those, a comparison change DOES\nreset it (service.Update), since the achieved flags it was computed from are no longer\ncomparable under the new comparison. The read path (fetchAndFoldGoalStats) returns\nmax(stored BestStreak, current window peak) so a peak from the still-visible window is\nreflected even before the next consolidation run persists it.", "type": "integer" }, "billable": { "type": "boolean" }, "client_ids": { "type": "array", "items": { "type": "integer" } }, "comparison": { "type": "string", "enum": [ "more_than", "less_than" ] }, "created_at": { "type": "string" }, "current_recurrence": { "$ref": "#/definitions/models.GoalRecurrence" }, "deleted_at": { "type": "string" }, "description": { "type": "string" }, "end_date": { "type": "string", "format": "date" }, "goal_id": { "type": "integer" }, "icon": { "type": "string" }, "is_syncing": { "description": "IsSyncing is true while the warehouse has not yet reflected the goal's latest\nconfiguration or activity, and clients should treat CurrentRecurrence's tracked time as\nstale/pending rather than a settled zero. This covers two cases: (1) a materialised\ncurrent period whose synced_at lags content_updated_at (a config edit is still being\nrecomputed), and (2) a period that has never been materialised on a goal created within\nthe last few minutes, but only when the current date falls within the goal's active\nwindow and the synthesised period is one the warehouse can actually generate (the async\npost-create warehouse refresh hasn't run yet). Past that initial window, or when no\nmaterialisable period exists at all (e.g. a future start_date), a never-materialised\nperiod is a true zero, not a pending sync.", "type": "boolean" }, "last_completed_recurrence_end_date": { "type": "string", "format": "date" }, "last_completed_recurrence_start_date": { "description": "LastCompletedRecurrenceStartDate is newer than the sibling EndDate field above and, unlike\nit, is marked optional (binding:\"optional\", x-nullable) so existing FE consumers built\nagainst the swagger schema before this field existed don't need a lockstep update just to\nkeep tsc green -- this is an additive field, not a required one.", "type": "string", "format": "date", "x-nullable": true }, "last_notified_at": { "type": "string" }, "monthly_anchor": { "type": "string", "enum": [ "calendar", "first_workday" ] }, "name": { "type": "string" }, "periods_met": { "description": "PeriodsMet/PeriodsTotal power the Goals page \"N of M periods met\" success-rate KPI.\nPeriodsMet = ConsolidatedPeriodsMet + achieved visible completed rows, clamped to\nPeriodsTotal (transient ETL/timezone states can briefly disagree with the Go calendar\nmath). PeriodsTotal is pure Go calendar math (see recurrence.go), not a warehouse read,\nsince warehouse rows behind the anchor are physically deleted.", "type": "integer" }, "periods_total": { "type": "integer" }, "permissions": { "type": "array", "items": { "type": "string" } }, "position": { "description": "Position is a per-(workspace_id, toggl_user_id) zero-based list ordering, controlled\nentirely by the FE via the reorder endpoint. It is bookkeeping, not user-facing content:\nchanging it must never bump ContentUpdatedAt (see the denylist in\ngoal_set_content_updated_at.sql), since that field drives IsSyncing and the warehouse\ndrift probe, and a visual-only reorder has nothing to reconcile.\nIntentionally excluded from the generic metadata-update path (internal/goal/sql/update.sql\ndoes not write this column) -- only create (append-to-end) and reorder (explicit\nreordering) may change it, to avoid a race where a concurrent Reorder's new position is\nsilently reverted by an in-flight Update that read the goal's old position.", "type": "integer" }, "previous_streak": { "type": "integer" }, "project_ids": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": "string", "enum": [ "daily", "weekly", "daily_workdays", "monthly" ] }, "start_date": { "type": "string", "format": "date" }, "status": { "$ref": "#/definitions/models.GoalStatus" }, "streak": { "type": "integer" }, "streak_consolidated_at": { "type": "string", "format": "date" }, "synced_at": { "type": "string" }, "tag_ids": { "type": "array", "items": { "type": "integer" } }, "target_seconds": { "type": "integer" }, "task_ids": { "type": "array", "items": { "type": "integer" } }, "toggl_user_id": { "type": "integer" }, "updated_at": { "type": "string" }, "week_start_on": { "description": "WeekStartOn (db column week_start_on) snapshots the weekday (0=Sunday, 1=Monday) a\nweekly goal's periods align to, captured at creation time from StartDate. It is\nimmutable thereafter, unlike the user's own settings.StartWeekOn (db column\nstart_week_on on user_settings -- note the transposed name), so toggling that setting\nlater cannot desync the warehouse materialization from the streak anchor\n(toggl/ic-tribe#1887). NULL for non-weekly goals and for weekly goals created before\nthis column existed.", "type": "integer", "x-nullable": true }, "weekdays": { "type": "array", "items": { "type": "integer" } }, "workspace_id": { "type": "integer" } } }, "models.GoalPreview": { "type": "object", "required": [ "period_end", "period_start", "tracked_seconds" ], "properties": { "achieved": { "type": "boolean", "x-nullable": true }, "period_end": { "type": "string", "format": "date" }, "period_start": { "type": "string", "format": "date" }, "tracked_seconds": { "type": "integer" } } }, "models.GoalRecurrence": { "type": "object", "required": [ "achieved", "comparison", "created_at", "deleted_at", "end_date", "goal_id", "goal_recurrence_id", "start_date", "synced_at", "target_seconds", "toggl_user_id", "tracked_seconds", "updated_at", "workspace_id" ], "properties": { "achieved": { "type": "boolean" }, "comparison": { "type": "string", "enum": [ "more_than", "less_than" ] }, "created_at": { "type": "string" }, "deleted_at": { "type": "string" }, "end_date": { "$ref": "#/definitions/models.DateOnly" }, "goal_id": { "type": "integer" }, "goal_recurrence_id": { "type": "integer" }, "start_date": { "$ref": "#/definitions/models.DateOnly" }, "synced_at": { "type": "string" }, "target_seconds": { "type": "integer" }, "toggl_user_id": { "type": "integer" }, "tracked_seconds": { "type": "integer" }, "updated_at": { "type": "string" }, "workspace_id": { "type": "integer" } } }, "models.GoalStatus": { "type": "string", "enum": [ "keep_going", "on_track", "on_a_streak", "reached", "failed" ], "x-enum-varnames": [ "GoalStatusKeepGoing", "GoalStatusOnTrack", "GoalStatusOnAStreak", "GoalStatusReached", "GoalStatusFailed" ] }, "models.GroupPagination": { "type": "object", "required": [ "page", "per_page" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "description": "null when group totals are not requested", "type": "integer" } } }, "models.IntegrationWithCalendars": { "type": "object", "required": [ "auto_track", "calendar_integration_id", "calendars", "created_at", "email", "error_status", "has_write_scope", "origin_product_id", "provider", "scopes" ], "properties": { "auto_track": { "type": "boolean" }, "calendar_integration_id": { "type": "integer" }, "calendars": { "type": "array", "items": { "$ref": "#/definitions/models.Calendar" } }, "created_at": { "type": "string" }, "email": { "type": "string" }, "error_status": { "type": "string" }, "has_write_scope": { "type": "boolean" }, "origin_product_id": { "description": "The product that initially integrated the calendar.", "type": "integer" }, "provider": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "models.MemberStatus": { "type": "string", "enum": [ "active", "discontinued" ], "x-enum-varnames": [ "MemberStatusActive", "MemberStatusDiscontinued" ] }, "models.Metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "models.Milestone": { "type": "object", "required": [ "color", "created_at", "due_date", "id", "name", "project_ids", "team_ids", "workspace_id" ], "properties": { "color": { "type": "string" }, "completed_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time" }, "due_date": { "type": "string", "format": "date" }, "id": { "type": "integer" }, "name": { "type": "string" }, "project_ids": { "type": "array", "items": { "type": "integer" } }, "team_ids": { "type": "array", "items": { "type": "integer" } }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "models.OnboardingAnswers": { "type": "object", "required": [ "answers", "created_at", "flow_key", "schema_version", "toggl_user_id", "updated_at", "workspace_id" ], "properties": { "answers": { "type": "object" }, "completed_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "flow_key": { "type": "string" }, "last_step": { "type": "string" }, "schema_version": { "type": "integer" }, "toggl_user_id": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "variant_key": { "type": "string" }, "workspace_id": { "type": "integer" } } }, "models.Page-models_Client": { "type": "object", "required": [ "data", "page", "per_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.Client" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "models.Page-models_Milestone": { "type": "object", "required": [ "data", "page", "per_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.Milestone" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "models.Page-models_Project": { "type": "object", "required": [ "data", "page", "per_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.Project" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "models.Page-models_ProjectWithAggregations": { "type": "object", "required": [ "data", "page", "per_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.ProjectWithAggregations" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "models.Page-models_Status": { "type": "object", "required": [ "data", "page", "per_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.Status" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "models.Page-models_Task": { "type": "object", "required": [ "data", "page", "per_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.Task" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "models.Page-models_TimeEntry": { "type": "object", "required": [ "data", "page", "per_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.TimeEntry" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "models.Page-task_TaskWithParentAndAggregations": { "type": "object", "required": [ "data", "page", "per_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/task.TaskWithParentAndAggregations" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "models.Page-timeblock_TimeBlockAggregate": { "type": "object", "required": [ "data", "page", "per_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/timeblock.TimeBlockAggregate" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "models.Page-timeblock_TimeBlockAggregateWithTask": { "type": "object", "required": [ "data", "page", "per_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/timeblock.TimeBlockAggregateWithTask" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "models.Page-timeentry_TimeEntryWithTask": { "type": "object", "required": [ "data", "page", "per_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/timeentry.TimeEntryWithTask" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "models.PageWithTotal-backoffice_ImportJobView": { "type": "object", "required": [ "data", "page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/backoffice.ImportJobView" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } }, "models.PageWithTotal-csv_UploadRequestResponse": { "type": "object", "required": [ "data", "page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/csv.UploadRequestResponse" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } }, "models.PageWithTotal-models_CustomFieldOption": { "type": "object", "required": [ "data", "page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.CustomFieldOption" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } }, "models.PageWithTotal-models_CustomFieldWithOptions": { "type": "object", "required": [ "data", "page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.CustomFieldWithOptions" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } }, "models.PageWithTotal-models_ProjectWithAggregations": { "type": "object", "required": [ "data", "page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.ProjectWithAggregations" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } }, "models.PageWithTotal-models_Tag": { "type": "object", "required": [ "data", "page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.Tag" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } }, "models.PageWithTotal-task_TaskWithParentAndAggregations": { "type": "object", "required": [ "data", "page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/task.TaskWithParentAndAggregations" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } }, "models.Periodicity": { "type": "string", "enum": [ "weekly", "monthly", "days" ], "x-enum-varnames": [ "PeriodicityWeekly", "PeriodicityMonthly", "PeriodicityDays" ] }, "models.PriceResponse": { "type": "object", "required": [ "billing_period_in_months", "cost_in_cents", "currency", "tag", "track_pricing_plan_id" ], "properties": { "billing_period_in_months": { "type": "integer" }, "cost_in_cents": { "type": "integer" }, "currency": { "type": "string" }, "tag": { "type": "string" }, "track_pricing_plan_id": { "type": "integer" } } }, "models.ProductResponse": { "type": "object", "required": [ "handle", "name", "site", "toggl_product_id", "track_enterprise", "track_plan_id" ], "properties": { "handle": { "type": "string" }, "name": { "type": "string" }, "site": { "type": "string" }, "toggl_product_id": { "type": "string" }, "track_enterprise": { "type": "boolean" }, "track_plan_id": { "type": "integer" } } }, "models.Project": { "type": "object", "required": [ "active", "auto_compute_estimates", "billable", "completion_mode", "created_at", "draft", "id", "is_template", "name", "permissions", "pinned", "private", "rollover_mode", "tag_ids", "tags", "toggl_user_id", "workspace_id" ], "properties": { "active": { "type": "boolean" }, "archived_at": { "type": "string", "format": "date-time" }, "auto_compute_estimates": { "type": "boolean" }, "billable": { "type": "boolean" }, "client": { "$ref": "#/definitions/models.ClientLite" }, "client_id": { "type": "integer" }, "color": { "type": "string" }, "completed_at": { "type": "string", "format": "date-time" }, "completion_mode": { "type": "string", "enum": [ "manual", "automatic" ] }, "created_at": { "type": "string", "format": "date-time" }, "custom_field_values": { "type": "array", "items": { "$ref": "#/definitions/models.CustomFieldValue" } }, "deleted_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "draft": { "type": "boolean" }, "end_date": { "type": "string", "format": "date" }, "estimated_mins": { "type": "integer" }, "fixed_fee": { "$ref": "#/definitions/models.ProjectFixedFee" }, "id": { "type": "integer" }, "is_template": { "type": "boolean" }, "name": { "type": "string" }, "parent_project_id": { "type": "integer" }, "permissions": { "type": "array", "items": { "type": "string" } }, "pinned": { "type": "boolean" }, "private": { "type": "boolean" }, "rate": { "$ref": "#/definitions/models.EffectiveProjectRatesSummary" }, "recurring_project_id": { "type": "integer" }, "rollover_mode": { "type": "string", "enum": [ "expire", "carry_all", "carry_over" ] }, "rrule": { "type": "string" }, "source_template_id": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "tag_ids": { "type": "array", "items": { "type": "integer" } }, "tags": { "type": "array", "items": { "$ref": "#/definitions/models.TagLite" } }, "toggl_user_id": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "models.ProjectAlertStatus": { "type": "object", "required": [ "has_active_alerts" ], "properties": { "estimate_used_pct": { "type": "number" }, "has_active_alerts": { "type": "boolean" }, "highest_triggered_threshold": { "type": "integer" } } }, "models.ProjectAssignmentMatchTier": { "type": "string", "enum": [ "exact_name", "similar_name" ], "x-enum-varnames": [ "ProjectAssignmentMatchTierExactName", "ProjectAssignmentMatchTierSimilarName" ] }, "models.ProjectAssignmentOrigin": { "type": "string", "enum": [ "manual", "auto_suggestion", "confirmed_suggestion", "integration", "legacy", "explicit_mapping" ], "x-enum-varnames": [ "ProjectAssignmentOriginManual", "ProjectAssignmentOriginAutoSuggestion", "ProjectAssignmentOriginConfirmedSuggestion", "ProjectAssignmentOriginIntegration", "ProjectAssignmentOriginLegacy", "ProjectAssignmentOriginExplicitMapping" ] }, "models.ProjectAttachment": { "type": "object", "required": [ "created_at", "display_order", "id", "mime_type", "project_id", "size" ], "properties": { "created_at": { "type": "string" }, "deleted_at": { "type": "string" }, "display_order": { "type": "integer" }, "id": { "type": "integer" }, "mime_type": { "type": "string" }, "name": { "type": "string" }, "project_id": { "type": "integer" }, "size": { "type": "integer" }, "updated_at": { "type": "string" } } }, "models.ProjectFixedFee": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number" }, "currency": { "type": "string" } } }, "models.ProjectGroup": { "type": "object", "required": [ "is_unassigned", "projects", "type" ], "properties": { "color": { "description": "Color is the option color; only set for cf grouping dimensions.", "type": "string" }, "id": { "description": "ID of the group entity (nil for the unassigned bucket).", "type": "integer" }, "is_unassigned": { "description": "IsUnassigned is true for the synthetic bucket of projects not belonging to any group entity.", "type": "boolean" }, "name": { "description": "Name of the group entity (nil for the unassigned bucket and for creator/assignee dims).", "type": "string" }, "pagination": { "description": "Pagination is only present when projects_per_group is set.", "allOf": [ { "$ref": "#/definitions/models.GroupPagination" } ] }, "position": { "description": "Position is the option catalog position; only set for cf grouping dimensions.", "type": "integer" }, "projects": { "description": "Projects belonging to this group (capped to projects_per_group when set).", "type": "array", "items": { "$ref": "#/definitions/models.ProjectWithAggregations" } }, "type": { "description": "Type identifies the grouping dimension: client, creator, tag, parent_project, assignee, or cf.", "type": "string", "enum": [ "client", "creator", "tag", "parent_project", "assignee", "cf" ] } } }, "models.ProjectLite": { "type": "object", "required": [ "draft", "id", "is_template", "name", "permissions" ], "properties": { "archived_at": { "type": "string", "format": "date-time" }, "client": { "$ref": "#/definitions/models.ClientLite" }, "color": { "type": "string" }, "custom_field_values": { "description": "CustomFieldValues are the parent project's CF values, hydrated by\ncallers that surface them (currently the task list, via\ntask.service.hydrateTaskProjectCustomFieldValues which routes through\ncustomfield.Service.GetFieldsByIDs and respects the\nPermissionViewWorkspaceProjectCustomFields gate). Producers that\ndon't hydrate (e.g. timeentry) leave the slice empty; omitempty\nhides it on those responses.", "type": "array", "items": { "$ref": "#/definitions/models.CustomFieldValue" } }, "draft": { "type": "boolean" }, "id": { "type": "integer" }, "is_template": { "type": "boolean" }, "name": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "private": { "type": "boolean" }, "rate": { "$ref": "#/definitions/models.EffectiveProjectRatesSummary" } } }, "models.ProjectWithAggregations": { "type": "object", "required": [ "active", "auto_compute_estimates", "billable", "completion_mode", "created_at", "draft", "id", "is_template", "name", "permissions", "pinned", "private", "rollover_mode", "tag_ids", "tags", "task_estimated_mins", "toggl_user_id", "total_tracked_secs", "workspace_id" ], "properties": { "active": { "type": "boolean" }, "alert_status": { "$ref": "#/definitions/models.ProjectAlertStatus" }, "archived_at": { "type": "string", "format": "date-time" }, "auto_compute_estimates": { "type": "boolean" }, "billable": { "type": "boolean" }, "client": { "$ref": "#/definitions/models.ClientLite" }, "client_id": { "type": "integer" }, "color": { "type": "string" }, "completed_at": { "type": "string", "format": "date-time" }, "completion_mode": { "type": "string", "enum": [ "manual", "automatic" ] }, "created_at": { "type": "string", "format": "date-time" }, "custom_field_values": { "type": "array", "items": { "$ref": "#/definitions/models.CustomFieldValue" } }, "deleted_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "draft": { "type": "boolean" }, "end_date": { "type": "string", "format": "date" }, "estimated_mins": { "type": "integer" }, "fixed_fee": { "$ref": "#/definitions/models.ProjectFixedFee" }, "id": { "type": "integer" }, "is_template": { "type": "boolean" }, "name": { "type": "string" }, "parent_project_id": { "type": "integer" }, "permissions": { "type": "array", "items": { "type": "string" } }, "pinned": { "type": "boolean" }, "private": { "type": "boolean" }, "rate": { "$ref": "#/definitions/models.EffectiveProjectRatesSummary" }, "recurring_project_id": { "type": "integer" }, "rollover_mins": { "description": "RolloverMins is the cumulative under/over budget carried into this\ninstance from earlier instances in its recurring chain, in minutes.\nPositive = surplus (prior periods went under estimate, time carries\nforward); negative = debt (prior periods went over). Only populated\nfor recurring instances; nil for templates and standalone projects.\nSee service.HydrateRollover for the per-instance contribution rules\ndriven by RolloverMode (expire / carry_over / carry_all).", "type": "integer", "x-nullable": true }, "rollover_mode": { "type": "string", "enum": [ "expire", "carry_all", "carry_over" ] }, "rrule": { "type": "string" }, "source_template_id": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "tag_ids": { "type": "array", "items": { "type": "integer" } }, "tags": { "type": "array", "items": { "$ref": "#/definitions/models.TagLite" } }, "task_estimated_mins": { "type": "integer" }, "toggl_user_id": { "type": "integer" }, "total_tasks": { "type": "integer" }, "total_tracked_secs": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "models.Rate": { "type": "object", "required": [ "currency", "end_date", "hourly_rate", "start_date" ], "properties": { "currency": { "type": "string" }, "end_date": { "type": "string" }, "hourly_rate": { "type": "number" }, "start_date": { "type": "string" } } }, "models.SavedView": { "type": "object", "required": [ "created_at", "id", "name", "params", "pinned", "toggl_user_id", "type", "workspace_id" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time" }, "icon_name": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "params": { "type": "object" }, "pinned": { "type": "boolean" }, "toggl_user_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "inbox", "archive", "board", "timeline", "project", "project.tasks", "project.board", "project.timeline", "projects", "reports.summary", "reports.detailed", "reports.utilization", "reports.workload", "reports.profitability" ] }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "models.Status": { "type": "object", "required": [ "created_at", "id", "name", "position", "type", "updated_at", "workspace_id" ], "properties": { "created_at": { "type": "string" }, "deleted_at": { "type": "string" }, "emoji": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "position": { "type": "integer" }, "type": { "$ref": "#/definitions/models.StatusType" }, "updated_at": { "type": "string" }, "workspace_id": { "type": "integer" } } }, "models.StatusLite": { "type": "object", "required": [ "id", "name", "type" ], "properties": { "emoji": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "$ref": "#/definitions/models.StatusType" } } }, "models.StatusType": { "type": "string", "enum": [ "todo", "done", "in_progress", "blocked" ], "x-enum-varnames": [ "StatusTypeTodo", "StatusTypeDone", "StatusTypeInProgress", "StatusTypeBlocked" ] }, "models.StreamEvent": { "type": "object", "required": [ "action", "created_at", "entity_id", "entity_type", "meta_data", "new_value", "old_value", "organization_id", "product_id", "project_id", "user_id", "workspace_id" ], "properties": { "action": { "type": "string" }, "created_at": { "type": "string" }, "entity_id": { "type": "integer" }, "entity_type": { "type": "string" }, "meta_data": { "$ref": "#/definitions/models.Metadata" }, "new_value": { "type": "object", "additionalProperties": {} }, "old_value": { "type": "object", "additionalProperties": {} }, "organization_id": { "type": "integer" }, "product_id": { "type": "integer" }, "project_id": { "type": "integer" }, "user_id": { "type": "integer" }, "workspace_id": { "type": "integer" } } }, "models.SubscriptionItemDiscountInfo": { "type": "object", "required": [ "amount_off", "coupon_id", "currency", "duration", "name", "percent_off", "promotion_code_id" ], "properties": { "amount_off": { "type": "integer" }, "coupon_id": { "type": "string" }, "currency": { "type": "string" }, "duration": { "type": "string" }, "name": { "type": "string" }, "percent_off": { "type": "number" }, "promotion_code_id": { "type": "string" } } }, "models.SubscriptionItemResponse": { "type": "object", "required": [ "discount", "quantity", "subscription_item_id", "updated_at" ], "properties": { "discount": { "$ref": "#/definitions/models.SubscriptionItemDiscountInfo" }, "quantity": { "type": "integer" }, "subscription_item_id": { "description": "ID is the Stripe subscription item ID. Empty for trial-only synthetic responses\nwhere no Stripe subscription item exists yet.", "type": "string" }, "updated_at": { "type": "string" } } }, "models.SubscriptionResponse": { "type": "object", "required": [ "customer", "id", "payment_failed", "state", "subscription_item", "url" ], "properties": { "customer": { "$ref": "#/definitions/models.CustomerResponse" }, "id": { "type": "string" }, "payment_failed": { "type": "boolean" }, "state": { "type": "string" }, "subscription_item": { "$ref": "#/definitions/models.SubscriptionItemResponse" }, "url": { "type": "string" } } }, "models.Tag": { "type": "object", "required": [ "created_at", "id", "name", "workspace_id" ], "properties": { "color": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time" }, "id": { "type": "integer" }, "name": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "models.TagLite": { "type": "object", "required": [ "id", "name" ], "properties": { "color": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } } }, "models.Task": { "type": "object", "required": [ "allocation_unit", "created_at", "estimate_type", "id", "is_template", "name", "pinned", "position", "priority", "private", "source", "status_id", "tag_ids", "tags", "toggl_user_id", "workspace_id" ], "properties": { "allocation_unit": { "type": "string", "enum": [ "percent", "flat" ] }, "archived_at": { "type": "string", "format": "date-time" }, "assignee_user_ids": { "type": "array", "items": { "type": "integer" } }, "assignees": { "description": "A unified column for all task entity assignments", "type": "array", "items": { "$ref": "#/definitions/models.TaskAssignment" } }, "auto_log_time": { "type": "boolean" }, "billable": { "type": "boolean" }, "client": { "$ref": "#/definitions/models.ClientLite" }, "color": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "custom_field_values": { "type": "array", "items": { "$ref": "#/definitions/models.CustomFieldValue" } }, "deleted_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "end_date": { "type": "string", "format": "date" }, "estimate_type": { "type": "string", "enum": [ "daily", "total" ] }, "estimated_mins": { "type": "integer" }, "id": { "type": "integer" }, "is_template": { "type": "boolean" }, "metadata": { "$ref": "#/definitions/models.TaskMetadata" }, "name": { "type": "string" }, "notes": { "type": "string" }, "parent_task_id": { "type": "integer" }, "parent_task_name": { "type": "string" }, "pinned": { "type": "boolean" }, "position": { "type": "integer" }, "priority": { "type": "string", "enum": [ "none", "low", "medium", "high" ] }, "priority_at": { "type": "string", "format": "date" }, "private": { "type": "boolean" }, "project": { "$ref": "#/definitions/models.ProjectLite" }, "project_id": { "type": "integer" }, "recurrence_date": { "type": "string", "format": "date" }, "recurring_task_id": { "type": "integer" }, "rrule": { "type": "string" }, "source": { "type": "string" }, "source_template_task_id": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "status": { "$ref": "#/definitions/models.StatusLite" }, "status_id": { "type": "integer" }, "status_updated_at": { "type": "string" }, "tag_ids": { "type": "array", "items": { "type": "integer" } }, "tags": { "type": "array", "items": { "$ref": "#/definitions/models.TagLite" } }, "toggl_user_id": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "models.TaskAssignment": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "integer" }, "type": { "$ref": "#/definitions/models.TaskAssignmentEntity" } } }, "models.TaskAssignmentEntity": { "type": "string", "enum": [ "user", "team" ], "x-enum-varnames": [ "TaskAssignmentEntityUser", "TaskAssignmentEntityTeam" ] }, "models.TaskAttachment": { "type": "object", "required": [ "created_at", "display_order", "id", "mime_type", "size", "task_id" ], "properties": { "created_at": { "type": "string" }, "deleted_at": { "type": "string" }, "display_order": { "type": "integer" }, "id": { "type": "integer" }, "mime_type": { "type": "string" }, "name": { "type": "string" }, "size": { "type": "integer" }, "task_id": { "type": "integer" }, "updated_at": { "type": "string" } } }, "models.TaskEstimateAllocation": { "type": "object", "required": [ "created_at", "id", "task_id", "toggl_user_id", "updated_at", "workspace_id" ], "properties": { "allocated_mins": { "type": "integer" }, "allocated_percent": { "type": "integer" }, "created_at": { "type": "string" }, "deleted_at": { "type": "string" }, "id": { "type": "integer" }, "task_id": { "type": "integer" }, "toggl_user_id": { "type": "integer" }, "updated_at": { "type": "string" }, "workspace_id": { "type": "integer" } } }, "models.TaskGroup": { "type": "object", "required": [ "id", "name", "tasks", "type" ], "properties": { "id": { "description": "The ID of one of the entities: projects/users/tags determined by `Type`.", "type": "integer" }, "name": { "description": "Display name of the group entity. Null for the users dimension, where the\nconsumer resolves the name from `ID` via Accounts.", "type": "string" }, "tasks": { "description": "The tasks that belong to the group.", "type": "array", "items": { "$ref": "#/definitions/models.EnrichedTaskGroupEntry" } }, "type": { "description": "`Type` determines what kind of group this is, and what table to look for\nbased on `ID`.", "type": "string", "enum": [ "projects", "users", "tags" ] } } }, "models.TaskLite": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "models.TaskMetadata": { "type": "object", "properties": { "all_day": { "type": "boolean" }, "calendar_event_id": { "type": "integer" }, "calendar_id": { "type": "integer" }, "extension_source": { "description": "Browser-extension provenance: the source/config that produced the task\nand the page URL it was tracked from. Written by the extension's\nstart-from-description flow; ExtensionURL is queryable via FindByURL.", "type": "string" }, "extension_url": { "type": "string" }, "external_id": { "type": "string" }, "ical_uid": { "type": "string" }, "last_asserted_track_project_id": { "description": "LastAssertedTrackProjectID is the Track planned_task.project_id that the\nFocus→Track mirror last successfully wrote for this task. Track→Focus\nuses it to distinguish a stale echo (Track still holds this value after\na Focus-side project move) from an intentional Track-side project move.\nInternal mirror state, written by toggl_api focus_sync_worker; not user-facing.", "type": "integer" }, "meeting_link": { "type": "string" }, "project_assignment": { "$ref": "#/definitions/models.TaskProjectAssignmentMetadata" }, "updated_at": { "type": "string", "format": "date-time" } } }, "models.TaskProjectAssignmentMetadata": { "type": "object", "required": [ "origin" ], "properties": { "accuracy": { "type": "number" }, "confirmed_at": { "type": "string", "format": "date-time" }, "match_tier": { "$ref": "#/definitions/models.ProjectAssignmentMatchTier" }, "matched_name": { "type": "string" }, "normalized_name": { "type": "string" }, "origin": { "$ref": "#/definitions/models.ProjectAssignmentOrigin" }, "suggested_at": { "type": "string", "format": "date-time" } } }, "models.TimeBlock": { "type": "object", "required": [ "created_at", "id", "start", "task_id", "toggl_user_id", "workspace_id" ], "properties": { "archived_at": { "type": "string", "format": "date-time" }, "calendar_event_id": { "type": "integer" }, "completed_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "duration": { "type": "integer" }, "id": { "type": "integer" }, "start": { "type": "string", "format": "date-time" }, "task_id": { "type": "integer" }, "timezone": { "description": "Timezone is the effective IANA timezone hydrated on reads: the workspace timezone\nsnapshotted at creation when set, else the creator's snapshot; NULL when unresolved.", "type": "string" }, "toggl_user_id": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "models.TimeEntry": { "type": "object", "required": [ "created_at", "id", "toggl_user_id", "type", "workspace_id" ], "properties": { "archived_at": { "type": "string", "format": "date-time" }, "billable": { "type": "boolean" }, "billable_source": { "enum": [ "manual", "task_default" ], "allOf": [ { "$ref": "#/definitions/models.BillableSource" } ] }, "calendar_event_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "duration": { "type": "integer" }, "id": { "type": "integer" }, "planned_at": { "type": "string", "format": "date-time" }, "planned_duration": { "type": "integer" }, "planned_start": { "type": "string", "format": "date-time" }, "project_id": { "type": "integer" }, "start": { "type": "string", "format": "date-time" }, "tag_ids": { "description": "TagIDs is the entry's manual tag override. NULL (nil) means no override:\nthe effective tags fall through to the linked task's tags. A non-nil\nvalue — including an empty array — is entry-authoritative.", "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "tags": { "description": "Tags is the hydrated effective tag set: the override when TagIDs is set,\nelse the linked task's active tags. Read-only.", "type": "array", "items": { "$ref": "#/definitions/models.TagLite" } }, "task_id": { "type": "integer", "x-nullable": true }, "time_block_id": { "type": "integer" }, "timezone": { "description": "Timezone is the effective IANA timezone hydrated on reads: the workspace timezone\nsnapshotted at creation when set, else the creator's snapshot; NULL when unresolved.", "type": "string" }, "toggl_user_id": { "type": "integer" }, "tracked_at": { "type": "string", "format": "date-time" }, "type": { "description": "The type of time entry: either an activity or a break.", "enum": [ "activity", "break" ], "allOf": [ { "$ref": "#/definitions/models.TimeEntryType" } ] }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "models.TimeEntryType": { "type": "string", "enum": [ "activity", "break" ], "x-enum-varnames": [ "TimeEntryTypeActivity", "TimeEntryTypeBreak" ] }, "models.Timesheet": { "type": "object", "required": [ "created_at", "current_layer", "end_date", "id", "setup_id", "start_date", "status", "user_account_id", "workspace_id" ], "properties": { "created_at": { "description": "CreatedAt is the row creation timestamp.", "type": "string", "format": "date-time" }, "current_layer": { "description": "CurrentLayer is the layer that must act next for the timesheet to\nadvance. On submission it is 0 (waiting on the lowest approver layer).\nAfter the approver at the current layer approves, it advances to the\nnext configured layer. Setup validation requires approver layers to be\ncontiguous from 0, so in practice that next layer is N+1; the traversal\n(nextLayerAfter) nonetheless does not assume contiguity. The timesheet\nreaches Status=approved when no higher configured layer remains to act.\n\nWhen an approver at layer N requests changes, status becomes\nchanges_requested with CurrentLayer=N. On resubmit, status\nreturns to submitted with CurrentLayer=N — the chain restarts at\nthe rejecting layer rather than at 0, preserving earlier-layer\napprovals.", "type": "integer" }, "deleted_at": { "description": "DeletedAt soft-deletes the timesheet. While set, the row is excluded\nfrom all read and materialisation paths. Set by the per-member\n\"Delete data\" action; nil means live.", "type": "string", "format": "date-time" }, "end_date": { "description": "EndDate is the inclusive end of this period.", "type": "string", "format": "date" }, "id": { "description": "ID is the surrogate key.", "type": "integer" }, "reviewed_at": { "description": "ReviewedAt is the timestamp of the most recent review action\n(approve, request-changes, withdraw, admin override).", "type": "string", "format": "date-time" }, "setup_id": { "description": "SetupID references the parent TimesheetSetup, which determines the\nperiod boundaries and the approval chain.", "type": "integer" }, "start_date": { "description": "StartDate is the inclusive start of this period. Must align with\nthe setup's period boundaries (validated on write).", "type": "string", "format": "date" }, "status": { "description": "Status is the current lifecycle state.", "enum": [ "not_submitted", "submitted", "approved", "changes_requested" ], "allOf": [ { "$ref": "#/definitions/models.TimesheetStatus" } ] }, "submitted_at": { "description": "SubmittedAt is when the member most recently submitted (or\nresubmitted) the timesheet. Nil for not_submitted rows.", "type": "string", "format": "date-time" }, "submitter_timezone": { "description": "SubmitterTimezone is a snapshot of the member's IANA timezone at\nsubmission time. Used so approvers see the member's data in the\nmember's local time even if the member later changes timezone.", "type": "string" }, "updated_at": { "description": "UpdatedAt tracks the last mutation.", "type": "string", "format": "date-time" }, "user_account_id": { "description": "UserAccountID identifies the member whose timesheet this is.", "type": "integer" }, "workspace_id": { "description": "WorkspaceID is the workspace the timesheet belongs to.", "type": "integer" } } }, "models.TimesheetFlag": { "type": "object", "required": [ "approver_user_account_id", "comment", "created_at", "id", "time_entry_id", "timesheet_id" ], "properties": { "approver_user_account_id": { "description": "ApproverUserAccountID is the user who created the flag.", "type": "integer" }, "comment": { "description": "Comment is the approver's note. Required and non-empty.", "type": "string" }, "created_at": { "description": "CreatedAt is the row creation timestamp.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "DeletedAt soft-deletes the flag. Set when the member resubmits,\nwhen the timesheet is approved, or when the underlying time entry\nis deleted.", "type": "string", "format": "date-time" }, "id": { "description": "ID is the surrogate key.", "type": "integer" }, "time_entry_id": { "description": "TimeEntryID references the time entry being flagged. The time\nentry must fall within the timesheet's period.", "type": "integer" }, "timesheet_id": { "description": "TimesheetID references the parent Timesheet.", "type": "integer" } } }, "models.TimesheetReview": { "type": "object", "required": [ "action", "actor_user_account_id", "created_at", "id", "timesheet_id" ], "properties": { "action": { "description": "Action is the action that was performed.", "enum": [ "submitted", "withdrawn", "approved", "changes_requested", "resubmitted", "approval_withdrawn", "admin_approved", "admin_changes_requested" ], "allOf": [ { "$ref": "#/definitions/models.TimesheetReviewAction" } ] }, "actor_user_account_id": { "description": "ActorUserAccountID is the user who performed the action.", "type": "integer" }, "comment": { "description": "Comment carries the message attached to the action. Required for\nchanges_requested and admin_changes_requested actions; optional\nfor others. Capped at 1000 characters.", "type": "string" }, "created_at": { "description": "CreatedAt is the timestamp of the action.", "type": "string", "format": "date-time" }, "id": { "description": "ID is the surrogate key.", "type": "integer" }, "layer": { "description": "Layer is the approver layer at which this action was taken. Nil\nfor actions taken outside the approver chain (admin overrides and\nmember submissions / withdrawals).", "type": "integer" }, "timesheet_id": { "description": "TimesheetID references the parent Timesheet.", "type": "integer" } } }, "models.TimesheetReviewAction": { "type": "string", "enum": [ "submitted", "withdrawn", "approved", "changes_requested", "resubmitted", "approval_withdrawn", "admin_approved", "admin_changes_requested" ], "x-enum-varnames": [ "TimesheetReviewActionSubmitted", "TimesheetReviewActionWithdrawn", "TimesheetReviewActionApproved", "TimesheetReviewActionChangesRequested", "TimesheetReviewActionResubmitted", "TimesheetReviewActionApprovalWithdrawn", "TimesheetReviewActionAdminApproved", "TimesheetReviewActionAdminChangesRequested" ] }, "models.TimesheetSetup": { "type": "object", "required": [ "created_at", "id", "periodicity", "start_date", "workspace_id" ], "properties": { "created_at": { "description": "CreatedAt is the row creation timestamp.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "DeletedAt soft-deletes the setup. While set, the setup is excluded\nfrom active queries and no new periods are generated for it.", "type": "string", "format": "date-time" }, "email_reminder_enabled": { "description": "EmailReminderEnabled gates the pending-reminder email channel for this\nsetup. When false (the default) the reminder cron skips this setup's\nmembers even if ReminderDay/ReminderTime are set.", "type": "boolean" }, "end_date": { "description": "EndDate is set when the setup is discontinued. While nil, the setup\ncontinues to generate periods indefinitely. When set, no new periods\nare generated past this date.", "type": "string", "format": "date" }, "id": { "description": "ID is the surrogate key.", "type": "integer" }, "period_days": { "description": "PeriodDays is the length of a period in days. Required (and minimum 1)\nwhen Periodicity == PeriodicityDays. Must be nil otherwise.", "type": "integer" }, "periodicity": { "description": "Periodicity defines the cadence of the timesheet periods.\nSee the Periodicity constants for valid values.", "enum": [ "weekly", "monthly", "days" ], "allOf": [ { "$ref": "#/definitions/models.Periodicity" } ] }, "reminder_day": { "description": "ReminderDay defines when in the period a reminder is sent to members\nwho haven't submitted yet. Interpretation depends on Periodicity:\n - weekly: 0..6 (0 = Sunday)\n - monthly: 1..31 (clamps to month length)\n - days: number of days into the period\nReminders are not sent when ReminderDay or ReminderTime is nil.", "type": "integer" }, "reminder_time": { "description": "ReminderTime is the wall-clock time the reminder is sent, formatted\nHH:MM, interpreted in each member's own timezone (resolved when the\nreminder cron runs; UTC when the member's timezone is unknown).\nReminders are not sent when ReminderDay or ReminderTime is nil.", "type": "string" }, "start_date": { "description": "StartDate is the anchor for period computation and the inclusive start\nof the very first period. All subsequent period boundaries derive\nfrom this date plus the periodicity rule.", "type": "string", "format": "date" }, "updated_at": { "description": "UpdatedAt tracks the last mutation. Nil for never-updated rows.", "type": "string", "format": "date-time" }, "workspace_id": { "description": "WorkspaceID is the workspace this setup belongs to.", "type": "integer" } } }, "models.TimesheetSetupApprover": { "type": "object", "required": [ "created_at", "id", "layer", "setup_id", "user_account_id", "workspace_id" ], "properties": { "created_at": { "description": "CreatedAt is the row creation timestamp.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "DeletedAt soft-deletes the approver assignment. While set, the row\nis treated as if the approver was never assigned.", "type": "string", "format": "date-time" }, "id": { "description": "ID is the surrogate key.", "type": "integer" }, "layer": { "description": "Layer is the 0-indexed tier of this approver in the approval\nchain. A layer may have multiple approvers (multiple rows sharing\nthe same setup_id and layer); any one of them acting is enough to\nadvance the timesheet to the next layer.", "type": "integer" }, "setup_id": { "description": "SetupID references the parent TimesheetSetup.", "type": "integer" }, "user_account_id": { "description": "UserAccountID is the approver's account identifier.", "type": "integer" }, "workspace_id": { "description": "WorkspaceID is the workspace this approver's setup belongs to.", "type": "integer" } } }, "models.TimesheetSetupMember": { "type": "object", "required": [ "created_at", "id", "setup_id", "status", "user_account_id", "workspace_id" ], "properties": { "created_at": { "description": "CreatedAt is the row creation timestamp.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "DeletedAt soft-deletes the membership. While set, the row is treated\nas if it didn't exist for membership checks.", "type": "string", "format": "date-time" }, "discontinued_at": { "description": "DiscontinuedAt marks the member as discontinued: they keep their past\ntimesheets but are excluded from setup resolution, so no new periods\nare generated for them. Nil means active; reactivation clears it.\nIndependent of DeletedAt (removal).", "type": "string", "format": "date-time" }, "id": { "description": "ID is the surrogate key.", "type": "integer" }, "setup_id": { "description": "SetupID references the parent TimesheetSetup.", "type": "integer" }, "status": { "description": "Status is the member's lifecycle state derived from DiscontinuedAt.\nIt is populated by the service layer and has no backing DB column.", "enum": [ "active", "discontinued" ], "allOf": [ { "$ref": "#/definitions/models.MemberStatus" } ] }, "user_account_id": { "description": "UserAccountID is the member's account identifier.", "type": "integer" }, "workspace_id": { "description": "WorkspaceID is the workspace this member's setup belongs to.", "type": "integer" } } }, "models.TimesheetStatus": { "type": "string", "enum": [ "not_submitted", "submitted", "approved", "changes_requested" ], "x-enum-varnames": [ "TimesheetStatusNotSubmitted", "TimesheetStatusSubmitted", "TimesheetStatusApproved", "TimesheetStatusChangesRequested" ] }, "models.TrackSubscriptionResponse": { "type": "object", "required": [ "cancel_date", "current_period_ends_at", "current_period_starts_at", "end_date", "payment_failed", "start_date", "subscription_created_at", "subscription_updated_at", "trial" ], "properties": { "cancel_date": { "type": "string" }, "current_period_ends_at": { "type": "string" }, "current_period_starts_at": { "type": "string" }, "end_date": { "type": "string" }, "payment_failed": { "type": "boolean" }, "start_date": { "type": "string" }, "subscription_created_at": { "type": "string" }, "subscription_updated_at": { "type": "string" }, "trial": { "$ref": "#/definitions/models.TrialResponse" } } }, "models.TrialResponse": { "type": "object", "required": [ "available", "end_date", "start_date", "trial_plan_id" ], "properties": { "available": { "type": "boolean" }, "end_date": { "type": "string" }, "start_date": { "type": "string" }, "trial_plan_id": { "type": "integer" } } }, "models.UserSettings": { "type": "object", "required": [ "theme" ], "properties": { "attachments_display_mode": { "type": "string", "enum": [ "list", "grid" ] }, "autocomplete_task_with_time_block": { "type": "boolean" }, "autolog_time": { "description": "Deprecated: gates auto-log only for the manual task-completion path (updateTaskAndRelated).\nPer-calendar sync auto-log behavior is now governed by the per-calendar focus_auto_track\nfield, not this setting.", "type": "boolean" }, "calendar_future_defaults_to_plan": { "description": "CalendarFutureDefaultsToPlan, when enabled, makes the unified-view event popover open future\nslots in Plan time (past slots stay Log time). When disabled (default) the unified view\nalways opens in Log time. Does not affect the split view.", "type": "boolean" }, "calendar_project_suggestion_fallback": { "description": "CalendarProjectSuggestionFallback enables automatic project suggestion for newly-created calendar tasks.", "type": "boolean" }, "calendar_range_type": { "type": "string" }, "calendar_show_calendar_events": { "type": "boolean" }, "calendar_show_completed_tasks": { "type": "boolean" }, "calendar_show_tasks_list": { "type": "boolean" }, "calendar_split_view_columns": { "type": "string" }, "calendar_task_creation_behavior": { "description": "CalendarTaskCreationBehavior controls how calendar events map to tasks during sync.", "type": "string", "enum": [ "always_create", "do_nothing", "match_existing" ] }, "current_workspace_id": { "type": "integer" }, "date_format": { "type": "string", "enum": [ "US", "EU", "ISO" ] }, "default_page": { "type": "string", "enum": [ "last-opened", "calendar", "inbox", "board", "timeline", "reports" ] }, "duration_format": { "type": "string", "enum": [ "classic", "improved", "decimal" ] }, "first_interaction": { "description": "FirstInteraction determines the settings update was the first user interaction\ndone. This is what is used to dispatch the Focus product sign-up event. This\nis not a setting that can be managed by FE. This is purely an internal BE\nsetting.", "type": "boolean" }, "first_interaction_date": { "description": "FirstInteractionDate records when the user first interacted with Focus.\nSet automatically by the BE alongside first_interaction.", "type": "string" }, "focus_mode_count_up": { "type": "boolean" }, "goal_reminder_time": { "description": "GoalReminderTime is the local clock time the daily goal reminder is sent, formatted HH:MM (24h).", "type": "string" }, "goal_reminders_enabled": { "description": "GoalRemindersEnabled opts the user into daily goal-reminder push notifications. Defaults to true.", "type": "boolean" }, "has_reached_task_threshold": { "description": "HasReachedTaskThreshold indicates the user has created 5+ tasks at some point.", "type": "boolean" }, "import_data_banner_dismissed": { "type": "boolean" }, "language_code": { "type": "string" }, "new_users_trial_dismissed": { "type": "boolean" }, "onboarding_calendar_step_at": { "description": "OnboardingCalendarStepAt is the ISO 8601 timestamp when the user left the calendar step (submitted or skipped)", "type": "string" }, "onboarding_checklist_dismissed": { "type": "boolean" }, "onboarding_completed_at": { "description": "OnboardingCompletedAt is the ISO 8601 timestamp when the user finished the onboarding flow", "type": "string" }, "onboarding_flow_dismissed": { "type": "boolean" }, "onboarding_multi_day_task_created": { "type": "boolean" }, "onboarding_started_at": { "description": "OnboardingStartedAt is the ISO 8601 timestamp when the user first saw the onboarding page", "type": "string" }, "onboarding_task_dragged": { "type": "boolean" }, "onboarding_tasks_step_at": { "description": "OnboardingTasksStepAt is the ISO 8601 timestamp when the user left the tasks step (submitted or skipped)", "type": "string" }, "onboarding_variant_selected": { "type": "string" }, "plan_tour_dismissed": { "description": "PlanTourDismissed indicates whether the user has dismissed the plan onboarding tour", "type": "boolean" }, "platform_nudges": { "description": "PlatformNudges maps a platform-discoverability nudge id to the ISO 8601 timestamp it was last\ndismissed. Keys are opaque to the backend (nudge ids are owned by the web app), so new nudges\nneed no backend change. Absent/empty means nothing has been dismissed.", "type": "object", "additionalProperties": { "type": "string" } }, "pomodoro_mode_auto_start_break": { "type": "boolean" }, "pomodoro_mode_break_duration_mins": { "type": "integer" }, "pomodoro_mode_session_duration_mins": { "type": "integer" }, "pomodoro_mode_sound_enabled": { "type": "boolean" }, "send_daily_brief": { "description": "SendDailyBrief opts the user into the morning Daily Brief email summarising yesterday's\ntracked time and today's plan. Defaults to true.", "type": "boolean" }, "send_timer_notifications": { "description": "SendTimerNotifications opts the user into the \"timer still running\" reminder email sent when\na timer has been left running for over 8 hours. Defaults to true.", "type": "boolean" }, "shortcuts_enabled": { "type": "boolean" }, "show_goals_panel": { "description": "ShowGoalsPanel controls whether the Goals panel is visible on the Timer page. Defaults to true.", "type": "boolean" }, "show_google_calendar_events": { "type": "boolean" }, "start_week_on": { "description": "StartWeekOn determines which day the week starts on: 0 for Sunday, 1 for Monday", "type": "integer", "enum": [ 0, 1 ] }, "switch_to_focus_dismissed": { "type": "boolean" }, "sync_external_calendar": { "description": "SyncExternalCalendar can either be 'never', 'always' or 'ask'", "type": "string" }, "theme": { "type": "string", "enum": [ "auto", "light", "dark" ] }, "time_block_color": { "type": "string" }, "time_format": { "type": "string", "enum": [ "12h", "24h" ] }, "time_tracking_mode": { "type": "string", "enum": [ "focus", "pomodoro" ] }, "time_tracking_mode_duration_mins": { "type": "integer" }, "time_tracking_mode_enabled": { "type": "boolean" }, "time_tracking_mode_fullscreen": { "type": "boolean" }, "timezone": { "description": "Timezone is the IANA timezone name (e.g. \"America/New_York\") used to localise time-sensitive\nfeatures such as goal current-period detection. Mirrors the timezone stored in Toggl Track.", "type": "string" }, "tooltip_onboarding_dismissed": { "description": "TooltipOnboardingDismissed indicates whether the user has dismissed the tooltip onboarding tour", "type": "boolean" }, "tos_ack_decoupled_licenses": { "description": "TosAckDecoupledLicenses maps an organization id to the ISO 8601 timestamp when\nthe user dismissed the seats-billing (decoupled-licenses) Terms-of-Service\nannouncement modal for that organization.", "type": "object", "additionalProperties": { "type": "string" } }, "trial_ended_modal_seen": { "description": "TrialEndedModalSeen maps an organization id to the ISO 8601 timestamp when the user was\nshown the end-of-trial modal for that organization. An absent entry for an org = not yet shown.", "type": "object", "additionalProperties": { "type": "string" } }, "welcome_modal_dismissed": { "description": "WelcomeModalDismissed indicates whether the user has dismissed the welcome modal", "type": "boolean" }, "whats_new_may_2026_dismissed": { "description": "WhatsNewMay2026Dismissed indicates whether the user has dismissed the May 2026 \"What's new\" tour", "type": "boolean" }, "whats_new_tasks_tour_dismissed": { "description": "WhatsNewTasksTourDismissed indicates whether the user has dismissed the tasks \"What's new\" tour", "type": "boolean" } } }, "models.UserWorkspaceSettings": { "type": "object", "properties": { "autolog_time": { "type": "boolean" } } }, "onboardinganswers.AnswersPayload": { "type": "object", "properties": { "integrations": { "type": "array", "items": { "type": "string" }, "x-nullable": true }, "primary_goal": { "type": "string", "x-nullable": true }, "role": { "type": "string", "x-nullable": true }, "team_size": { "type": "string", "x-nullable": true }, "uses_calendar": { "type": "boolean", "x-nullable": true } } }, "onboardinganswers.PartialUpdatePayload": { "type": "object", "properties": { "answers": { "$ref": "#/definitions/onboardinganswers.AnswersPayload" }, "completed": { "type": "boolean" }, "flow_key": { "type": "string" }, "last_step": { "type": "string" }, "schema_version": { "type": "integer" }, "variant_key": { "type": "string" } } }, "organization.GroupRequest": { "type": "object", "required": [ "emoji", "name", "organization_users", "workspaces" ], "properties": { "emoji": { "type": "string" }, "name": { "type": "string" }, "organization_users": { "type": "array", "items": { "type": "integer" } }, "workspaces": { "type": "array", "items": { "type": "integer" } } } }, "organization.GroupUserRoleRequest": { "type": "object", "required": [ "focus_role_id", "organization_user_id", "workspace_id" ], "properties": { "focus_role_id": { "type": "integer", "x-nullable": true }, "organization_user_id": { "type": "integer" }, "workspace_id": { "type": "integer" } } }, "organization.MemberTag": { "type": "object", "required": [ "color", "created_at", "id", "label", "organization_id", "updated_at" ], "properties": { "color": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "integer" }, "label": { "type": "string" }, "organization_id": { "type": "integer" }, "updated_at": { "type": "string" } } }, "organization.OrgUserEffectiveRate": { "type": "object", "required": [ "currency", "end_at", "hourly_rate", "start_at", "workspace_id", "workspace_rate_id", "workspace_user_rate_id" ], "properties": { "currency": { "type": "string" }, "end_at": { "type": "string" }, "hourly_rate": { "type": "number" }, "start_at": { "type": "string" }, "workspace_id": { "type": "integer" }, "workspace_rate_id": { "type": "integer" }, "workspace_user_rate_id": { "type": "integer" } } }, "organization.OrganizationUserGroupExtendedResponse": { "type": "object", "required": [ "emoji", "id", "name", "workspace_ids" ], "properties": { "emoji": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "workspace_ids": { "type": "array", "items": { "type": "integer" } } } }, "organization.OrganizationUserGroupResponse": { "type": "object", "required": [ "emoji", "id", "name" ], "properties": { "emoji": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } } }, "organization.OrganizationUserResponse": { "type": "object", "required": [ "2fa_enabled", "account_locked_at", "active", "admin", "can_edit_personal_details", "created_at", "deleted_at", "email", "groups", "id", "invite_sent", "joined", "name", "organization_id", "owner", "permissions", "rate", "tags", "updated_at", "user_account_id", "user_id", "working_hours", "workspaces" ], "properties": { "2fa_enabled": { "type": "boolean" }, "account_locked_at": { "type": "string" }, "active": { "type": "boolean" }, "admin": { "type": "boolean" }, "can_edit_personal_details": { "type": "boolean" }, "created_at": { "type": "string" }, "custom_field_values": { "description": "CustomFieldValues carries the member's user-level custom-field values.\nPresent only when the list is called with include_custom_fields=true on\na single workspace and the caller holds\nview_workspace_user_custom_fields with the beta enabled; omitted\notherwise. Kept on this type (rather than a separate response type) so\nthe generated client's OrganizationUserResponse keeps its name — FE\ncode imports it directly.", "type": "array", "items": { "$ref": "#/definitions/models.CustomFieldValue" } }, "deleted_at": { "type": "string" }, "email": { "type": "string" }, "groups": { "type": "array", "items": { "$ref": "#/definitions/organization.OrganizationUserGroupExtendedResponse" } }, "id": { "type": "integer" }, "invite_sent": { "type": "boolean" }, "joined": { "type": "boolean" }, "name": { "type": "string" }, "organization_id": { "type": "integer" }, "owner": { "type": "boolean" }, "permissions": { "type": "object", "additionalProperties": {} }, "rate": { "$ref": "#/definitions/organization.OrgUserEffectiveRate" }, "tags": { "type": "array", "items": { "$ref": "#/definitions/organization.OrganizationUserTagResponse" } }, "updated_at": { "type": "string" }, "user_account_id": { "type": "integer" }, "user_id": { "type": "string" }, "working_hours": { "type": "number" }, "workspaces": { "type": "array", "items": { "$ref": "#/definitions/organization.OrganizationUserWorkspaceResponse" } } } }, "organization.OrganizationUserTagResponse": { "type": "object", "required": [ "color", "id", "label" ], "properties": { "color": { "type": "string" }, "id": { "type": "integer" }, "label": { "type": "string" } } }, "organization.OrganizationUserWorkspaceResponse": { "type": "object", "required": [ "focus_role_id", "groups", "id", "name", "toggl_products", "track_role_id", "work_role_id", "workspace_user_id" ], "properties": { "focus_role_id": { "type": "integer" }, "groups": { "type": "array", "items": { "$ref": "#/definitions/organization.OrganizationUserGroupResponse" } }, "id": { "type": "integer" }, "name": { "type": "string" }, "toggl_products": { "type": "array", "items": { "type": "string" } }, "track_role_id": { "type": "integer" }, "work_role_id": { "type": "integer" }, "workspace_user_id": { "type": "integer" } } }, "orgprivate.Group": { "type": "object", "required": [ "created_at", "deleted_at", "emoji", "id", "name", "organization_id", "updated_at", "users", "workspaces" ], "properties": { "created_at": { "type": "string", "example": "2021-09-01T00:00:00Z" }, "deleted_at": { "type": "string", "example": "2021-09-01T00:00:00Z" }, "emoji": { "type": "string", "example": "😀" }, "id": { "type": "integer", "example": 20000000 }, "name": { "type": "string", "example": "Group Name" }, "organization_id": { "type": "integer", "example": 20000000 }, "updated_at": { "type": "string", "example": "2021-09-01T00:00:00Z" }, "users": { "type": "array", "items": { "$ref": "#/definitions/client.UserGroupExtended" } }, "workspaces": { "type": "array", "items": { "$ref": "#/definitions/client.WorkspaceGroupExtended" } } } }, "page.Envelope-models_EffectiveProjectRatesSummary": { "type": "object", "required": [ "data", "page", "rows", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.EffectiveProjectRatesSummary" } }, "page": { "type": "integer" }, "rows": { "type": "integer" }, "total": { "type": "integer" } } }, "page.Envelope-orgprivate_Group": { "type": "object", "required": [ "data", "page", "rows", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/orgprivate.Group" } }, "page": { "type": "integer" }, "rows": { "type": "integer" }, "total": { "type": "integer" } } }, "presence.PlatformLastSeen": { "type": "object", "required": [ "last_seen_at", "platform" ], "properties": { "last_seen_at": { "type": "string", "format": "date-time" }, "platform": { "$ref": "#/definitions/events.PlatformOrigin" } } }, "project.BulkArchivePayload": { "type": "object", "required": [ "project_ids" ], "properties": { "project_ids": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "type": "integer" } } } }, "project.BulkRestorePayload": { "type": "object", "required": [ "project_ids" ], "properties": { "project_ids": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "type": "integer" } } } }, "project.BulkUnarchivePayload": { "type": "object", "required": [ "project_ids" ], "properties": { "project_ids": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "type": "integer" } } } }, "project.BulkUserEntry": { "type": "object", "required": [ "role_id", "user_id" ], "properties": { "role_id": { "type": "integer" }, "user_id": { "type": "integer" } } }, "project.CompleteProjectResponse": { "type": "object", "required": [ "project" ], "properties": { "next_instance": { "allOf": [ { "$ref": "#/definitions/models.Project" } ], "x-nullable": true }, "project": { "$ref": "#/definitions/models.Project" } } }, "project.CreateFromTemplatePayload": { "type": "object", "properties": { "end_date": { "type": "string", "format": "date" }, "name": { "type": "string" }, "pinned": { "type": "boolean" }, "start_date": { "type": "string", "format": "date" } } }, "project.CreateInstancePayload": { "type": "object", "properties": { "auto_compute_estimates": { "type": "boolean" }, "billable": { "type": "boolean" }, "client_id": { "type": "integer", "x-nullable": true }, "description": { "type": "string", "x-nullable": true }, "estimated_mins": { "type": "integer", "minimum": 0, "x-nullable": true }, "fixed_fee": { "allOf": [ { "$ref": "#/definitions/project.FixedFeePayload" } ], "x-nullable": true }, "private": { "type": "boolean" }, "tag_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true } } }, "project.CreateInstanceResult": { "type": "object", "required": [ "active", "auto_compute_estimates", "billable", "completion_mode", "created_at", "draft", "id", "is_template", "name", "permissions", "pinned", "private", "projection_revision", "rollover_mode", "tag_ids", "tags", "task_id_by_template_task_id", "toggl_user_id", "workspace_id" ], "properties": { "active": { "type": "boolean" }, "archived_at": { "type": "string", "format": "date-time" }, "auto_compute_estimates": { "type": "boolean" }, "billable": { "type": "boolean" }, "client": { "$ref": "#/definitions/models.ClientLite" }, "client_id": { "type": "integer" }, "color": { "type": "string" }, "completed_at": { "type": "string", "format": "date-time" }, "completion_mode": { "type": "string", "enum": [ "manual", "automatic" ] }, "created_at": { "type": "string", "format": "date-time" }, "custom_field_values": { "type": "array", "items": { "$ref": "#/definitions/models.CustomFieldValue" } }, "deleted_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "draft": { "type": "boolean" }, "end_date": { "type": "string", "format": "date" }, "estimated_mins": { "type": "integer" }, "fixed_fee": { "$ref": "#/definitions/models.ProjectFixedFee" }, "id": { "type": "integer" }, "is_template": { "type": "boolean" }, "name": { "type": "string" }, "parent_project_id": { "type": "integer" }, "permissions": { "type": "array", "items": { "type": "string" } }, "pinned": { "type": "boolean" }, "private": { "type": "boolean" }, "projection_revision": { "type": "string" }, "rate": { "$ref": "#/definitions/models.EffectiveProjectRatesSummary" }, "recurring_project_id": { "type": "integer" }, "rollover_mode": { "type": "string", "enum": [ "expire", "carry_all", "carry_over" ] }, "rrule": { "type": "string" }, "source_template_id": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "tag_ids": { "type": "array", "items": { "type": "integer" } }, "tags": { "type": "array", "items": { "$ref": "#/definitions/models.TagLite" } }, "task_id_by_template_task_id": { "type": "object", "additionalProperties": { "type": "integer" } }, "toggl_user_id": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "project.CreateTemplateFromProjectPayload": { "type": "object", "properties": { "auto_compute_estimates": { "type": "boolean" }, "estimated_mins": { "type": "integer", "minimum": 0 }, "fixed_fee": { "$ref": "#/definitions/project.FixedFeePayload" }, "name": { "type": "string" }, "rrule": { "type": "string" } } }, "project.DuplicatePayload": { "type": "object", "properties": { "name": { "type": "string" } } }, "project.FixedFeePayload": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number" }, "currency": { "type": "string" } } }, "project.NewRate": { "type": "object", "required": [ "currency", "hourly_rate", "start_at" ], "properties": { "currency": { "type": "string" }, "end_at": { "type": "string" }, "hourly_rate": { "type": "number" }, "start_at": { "type": "string" } } }, "project.PartialUpdatePayload": { "type": "object", "properties": { "auto_compute_estimates": { "type": "boolean" }, "billable": { "type": "boolean" }, "client_id": { "type": "integer", "x-nullable": true }, "color": { "type": "string", "x-nullable": true }, "completion_mode": { "type": "string", "enum": [ "manual", "automatic" ] }, "custom_fields": { "type": "object", "x-nullable": true }, "description": { "type": "string", "x-nullable": true }, "draft": { "type": "boolean" }, "end_date": { "type": "string", "format": "date", "x-nullable": true }, "estimated_mins": { "type": "integer", "minimum": 0, "x-nullable": true }, "fixed_fee": { "allOf": [ { "$ref": "#/definitions/project.FixedFeePayload" } ], "x-nullable": true }, "name": { "type": "string" }, "parent_project_id": { "type": "integer", "x-nullable": true }, "pinned": { "type": "boolean" }, "private": { "type": "boolean" }, "rollover_mode": { "type": "string", "enum": [ "expire", "carry_all", "carry_over" ] }, "rrule": { "type": "string", "x-nullable": true }, "start_date": { "type": "string", "format": "date", "x-nullable": true }, "tag_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true } } }, "project.PartialUpdatePayloadWithID": { "type": "object", "required": [ "id" ], "properties": { "auto_compute_estimates": { "type": "boolean" }, "billable": { "type": "boolean" }, "client_id": { "type": "integer", "x-nullable": true }, "color": { "type": "string", "x-nullable": true }, "completion_mode": { "type": "string", "enum": [ "manual", "automatic" ] }, "custom_fields": { "type": "object", "x-nullable": true }, "description": { "type": "string", "x-nullable": true }, "draft": { "type": "boolean" }, "end_date": { "type": "string", "format": "date", "x-nullable": true }, "estimated_mins": { "type": "integer", "minimum": 0, "x-nullable": true }, "fixed_fee": { "allOf": [ { "$ref": "#/definitions/project.FixedFeePayload" } ], "x-nullable": true }, "id": { "type": "integer" }, "name": { "type": "string" }, "parent_project_id": { "type": "integer", "x-nullable": true }, "pinned": { "type": "boolean" }, "private": { "type": "boolean" }, "rollover_mode": { "type": "string", "enum": [ "expire", "carry_all", "carry_over" ] }, "rrule": { "type": "string", "x-nullable": true }, "start_date": { "type": "string", "format": "date", "x-nullable": true }, "tag_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "users": { "type": "array", "items": { "$ref": "#/definitions/project.BulkUserEntry" }, "x-nullable": true } } }, "project.Payload": { "type": "object", "required": [ "name" ], "properties": { "auto_compute_estimates": { "type": "boolean" }, "billable": { "type": "boolean" }, "client_id": { "type": "integer" }, "color": { "type": "string" }, "completion_mode": { "type": "string", "enum": [ "manual", "automatic" ] }, "custom_fields": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" }, "draft": { "type": "boolean" }, "end_date": { "type": "string", "format": "date" }, "estimated_mins": { "type": "integer", "minimum": 0 }, "fixed_fee": { "$ref": "#/definitions/project.FixedFeePayload" }, "is_template": { "type": "boolean" }, "name": { "type": "string" }, "parent_project_id": { "type": "integer" }, "pinned": { "type": "boolean" }, "private": { "type": "boolean" }, "rollover_mode": { "type": "string", "enum": [ "expire", "carry_all", "carry_over" ] }, "rrule": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "tag_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true } } }, "project.RateAPI": { "type": "object", "required": [ "currency", "hourly_rate", "start_at" ], "properties": { "currency": { "type": "string" }, "end_at": { "type": "string" }, "hourly_rate": { "type": "number" }, "project_rate_id": { "type": "integer" }, "start_at": { "type": "string" }, "workspace_rate_id": { "type": "integer" } } }, "projectattachment.Payload": { "type": "object", "required": [ "display_order", "name" ], "properties": { "display_order": { "type": "integer" }, "name": { "type": "string" } } }, "projectgroup.projectGroupsResponse": { "type": "object", "required": [ "data", "is_truncated", "page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.ProjectGroup" } }, "is_truncated": { "description": "IsTruncated is true when the workspace has more than 5000 distinct projects across\nthe requested page of groups. Some groups may contain fewer projects than their total\nindicates. Use projects_per_group with tighter filters to avoid truncation.", "type": "boolean" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_distinct": { "type": "integer" } } }, "projectmargintarget.ListItem": { "type": "object", "required": [ "project_id", "target_percent" ], "properties": { "project_id": { "type": "integer", "x-nullable": true }, "target_percent": { "type": "integer" } } }, "projectmargintarget.Response": { "type": "object", "required": [ "scope", "target_percent", "workspace_id" ], "properties": { "scope": { "description": "\"project\" | \"workspace\" | null", "type": "string", "x-nullable": true }, "target_percent": { "type": "integer", "x-nullable": true }, "workspace_id": { "type": "integer" } } }, "projectmargintarget.SetPayload": { "type": "object", "required": [ "target_percent" ], "properties": { "target_percent": { "type": "integer", "maximum": 100, "minimum": 1 } } }, "projectuser.PostProjectMembers": { "type": "object", "required": [ "role_id" ], "properties": { "group_ids": { "type": "array", "items": { "type": "integer" } }, "role_id": { "type": "integer" }, "user_ids": { "type": "array", "items": { "type": "integer" } } } }, "projectuser.ProjectGroup": { "type": "object", "required": [ "group_id" ], "properties": { "group_id": { "type": "integer" }, "manager": { "type": "boolean", "x-nullable": true } } }, "projectuser.ProjectMembers": { "type": "object", "required": [ "group_ids", "project_id", "user_ids" ], "properties": { "group_ids": { "type": "array", "items": { "$ref": "#/definitions/projectuser.ProjectGroup" } }, "project_id": { "type": "integer" }, "user_ids": { "type": "array", "items": { "$ref": "#/definitions/projectuser.ProjectUser" } } } }, "projectuser.ProjectUser": { "type": "object", "required": [ "manager", "user_id" ], "properties": { "manager": { "type": "boolean" }, "user_id": { "type": "integer" } } }, "projectuser.deleteProjectMember": { "type": "object", "properties": { "group_id": { "type": "integer" }, "user_id": { "type": "integer" } } }, "projectuser.updateMemberRole": { "type": "object", "required": [ "role_id" ], "properties": { "group_id": { "type": "integer" }, "role_id": { "type": "integer" }, "user_id": { "type": "integer" } } }, "rate.ConflictCheckResult": { "type": "object", "properties": { "deleted": { "type": "array", "items": { "$ref": "#/definitions/rate.RateAPI" } }, "modified": { "type": "array", "items": { "$ref": "#/definitions/rate.ModifiedRate" } } } }, "rate.ModifiedRate": { "type": "object", "required": [ "current", "new" ], "properties": { "current": { "$ref": "#/definitions/rate.RateAPI" }, "new": { "$ref": "#/definitions/rate.RateAPIShort" } } }, "rate.NewRatePayload": { "type": "object", "required": [ "currency", "hourly_rate", "start_date" ], "properties": { "currency": { "type": "string" }, "end_date": { "type": "string", "format": "date" }, "hourly_rate": { "type": "integer", "minimum": 0 }, "start_date": { "type": "string", "format": "date" } } }, "rate.RateAPI": { "type": "object", "required": [ "currency", "hourly_rate", "id", "start_date" ], "properties": { "currency": { "type": "string" }, "end_date": { "type": "string", "format": "date" }, "hourly_rate": { "type": "integer" }, "id": { "type": "integer" }, "start_date": { "type": "string", "format": "date" } } }, "rate.RateAPIShort": { "type": "object", "required": [ "id", "start_date" ], "properties": { "end_date": { "type": "string", "format": "date" }, "id": { "type": "integer" }, "start_date": { "type": "string", "format": "date" } } }, "rate.RateWithEntityAPI": { "type": "object", "required": [ "currency", "entity_id", "hourly_rate", "id", "start_date" ], "properties": { "currency": { "type": "string" }, "end_date": { "type": "string", "format": "date" }, "entity_id": { "type": "integer" }, "hourly_rate": { "type": "integer" }, "id": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "sub_entity_id": { "type": "integer" } } }, "recurringbudget.suggestionResponse": { "type": "object", "required": [ "basis_median_mins", "confidence", "current_budget_mins", "high_mins", "low_mins", "n_periods", "status", "suggested_mins" ], "properties": { "basis_median_mins": { "type": "integer" }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] }, "current_budget_mins": { "type": "integer" }, "high_mins": { "type": "integer" }, "low_mins": { "type": "integer" }, "n_periods": { "type": "integer" }, "status": { "description": "Status explains the result; the fields below are only set when it is\n\"suggested\". The empty cases (no_history / too_varied) let the client\ngive feedback instead of rendering nothing.", "type": "string", "enum": [ "suggested", "no_history", "too_varied", "on_track", "dismissed" ] }, "suggested_mins": { "type": "integer" } } }, "response.Error": { "type": "object", "required": [ "error", "error_description" ], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "error_values": { "type": "object", "additionalProperties": {} }, "trace_id": { "type": "string" } } }, "savedview.CreatePayload": { "type": "object", "required": [ "name", "params", "pinned", "type" ], "properties": { "icon_name": { "type": "string", "maxLength": 255 }, "name": { "type": "string" }, "params": { "type": "object" }, "pinned": { "type": "boolean" }, "type": { "type": "string", "enum": [ "inbox", "archive", "board", "timeline", "project", "project.tasks", "project.board", "project.timeline", "projects", "reports.summary", "reports.detailed", "reports.utilization", "reports.workload", "reports.profitability" ] } } }, "savedview.UpdatePayload": { "type": "object", "required": [ "name", "params", "pinned", "type" ], "properties": { "icon_name": { "type": "string", "maxLength": 255 }, "name": { "type": "string" }, "params": { "type": "object" }, "pinned": { "type": "boolean" }, "type": { "type": "string", "enum": [ "inbox", "archive", "board", "timeline", "project", "project.tasks", "project.board", "project.timeline", "projects", "reports.summary", "reports.detailed", "reports.utilization", "reports.workload", "reports.profitability" ] } } }, "search.MentionMember": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "search.MentionTag": { "type": "object", "required": [ "id", "name" ], "properties": { "color": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } } }, "search.MentionsResult": { "type": "object", "required": [ "degraded", "members", "projects", "tags" ], "properties": { "degraded": { "type": "array", "items": { "type": "string" } }, "members": { "type": "array", "items": { "$ref": "#/definitions/search.MentionMember" } }, "projects": { "type": "array", "items": { "$ref": "#/definitions/search.ProjectResult" } }, "tags": { "type": "array", "items": { "$ref": "#/definitions/search.MentionTag" } } } }, "search.ProjectResult": { "type": "object", "required": [ "id", "name" ], "properties": { "client_name": { "type": "string" }, "color": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } } }, "search.Result": { "type": "object", "required": [ "projects", "tasks", "time_entries" ], "properties": { "projects": { "type": "array", "items": { "$ref": "#/definitions/search.ProjectResult" } }, "tasks": { "type": "array", "items": { "$ref": "#/definitions/search.TaskResult" } }, "time_entries": { "type": "array", "items": { "$ref": "#/definitions/search.TimeEntryResult" } } } }, "search.TaskResult": { "type": "object", "required": [ "id", "name" ], "properties": { "client_name": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "project_color": { "type": "string" }, "project_id": { "type": "integer" }, "project_name": { "type": "string" } } }, "search.TimeEntryResult": { "type": "object", "required": [ "description", "last_tracked_at" ], "properties": { "description": { "type": "string" }, "last_tracked_at": { "type": "string", "format": "date-time" }, "project_color": { "type": "string" }, "project_id": { "type": "integer" }, "project_name": { "type": "string" }, "tag_ids": { "description": "TagIDs is the tag override a resumed entry should carry. NULL (nil) means\ninherit from the linked task, which is also what an effective tag set equal\nto the task's own active set normalizes to. Never omitted: inherit has to\nreach the client as an explicit null. Mirrors models.TimeEntry.TagIDs.\nPopulated only when group_by_tags is requested, else always null.", "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "tags": { "description": "Tags is the hydrated effective tag set for display: the entry override when\nset, else the linked task's tags, active tags only. Read-only.\nPopulated only when group_by_tags is requested, else always empty.", "type": "array", "items": { "$ref": "#/definitions/models.TagLite" } }, "task_id": { "type": "integer" }, "task_name": { "type": "string" } } }, "shareddata.PublicHolidayWithUserAccountID": { "type": "object", "required": [ "country", "date", "name", "user_account_id" ], "properties": { "country": { "type": "string" }, "date": { "type": "string" }, "name": { "type": "string" }, "user_account_id": { "type": "integer" } } }, "shareddata.TimeOffWithoutPersonalInfo": { "type": "object", "required": [ "end_time", "start_time", "timeoff_id", "user_id" ], "properties": { "end_time": { "description": "EndTime is the RFC3339 timestamp (UTC) the time off period ends at; always after StartTime.", "type": "string" }, "start_time": { "description": "StartTime is the RFC3339 timestamp (UTC) the time off period starts at.", "type": "string" }, "timeoff_id": { "description": "ID is the unique identifier of the time off entry.", "type": "integer" }, "user_id": { "description": "UserID is the user the time off was booked for.", "type": "integer" } } }, "shareddata.WorkingHours": { "type": "object", "required": [ "created_at", "organization_id", "updated_at", "working_hour_id", "working_hours" ], "properties": { "created_at": { "type": "string" }, "external_entity_id": { "type": "integer" }, "external_entity_type": { "type": "string" }, "organization_id": { "type": "integer" }, "starting_hours": { "type": "number" }, "updated_at": { "type": "string" }, "user_id": { "type": "integer" }, "weekday": { "type": "integer" }, "working_hour_id": { "type": "integer" }, "working_hours": { "type": "number" } } }, "shareddata.WorkingHoursCreateInput": { "type": "object", "required": [ "working_hours" ], "properties": { "weekday": { "type": "integer", "maximum": 6, "minimum": 0 }, "working_hours": { "type": "number", "maximum": 168 } } }, "shareddata.WorkingHoursUpdateInput": { "type": "object", "required": [ "working_hour_id", "working_hours" ], "properties": { "weekday": { "type": "integer", "maximum": 6, "minimum": 0 }, "working_hour_id": { "type": "integer" }, "working_hours": { "type": "number", "maximum": 168 } } }, "status.Payload": { "type": "object", "required": [ "emoji", "name", "position" ], "properties": { "emoji": { "type": "string" }, "name": { "type": "string" }, "position": { "type": "integer", "minimum": 1 } } }, "subscription.getCurrentResponse": { "type": "object", "required": [ "focus_trial_ended_at", "organization_id", "price", "product", "subscription", "subscription_item", "track_subscription" ], "properties": { "focus_trial_ended_at": { "type": "string", "format": "date-time", "x-nullable": true }, "organization_id": { "type": "integer" }, "price": { "$ref": "#/definitions/models.PriceResponse" }, "product": { "$ref": "#/definitions/models.ProductResponse" }, "subscription": { "$ref": "#/definitions/models.SubscriptionResponse" }, "subscription_item": { "$ref": "#/definitions/models.SubscriptionItemResponse" }, "track_subscription": { "$ref": "#/definitions/models.TrackSubscriptionResponse" } } }, "subscription.getCurrentTrialResponse": { "type": "object", "required": [ "id", "organization_id", "plan_id", "plan_name", "product_handle", "toggl_product_name", "trial_cancels_at", "trial_created_at", "trial_deleted_at", "trial_ended_at", "trial_started_at", "trial_type" ], "properties": { "id": { "type": "integer" }, "organization_id": { "type": "integer" }, "plan_id": { "type": "integer" }, "plan_name": { "type": "string" }, "product_handle": { "type": "string" }, "toggl_product_name": { "type": "string" }, "trial_cancels_at": { "type": "string" }, "trial_created_at": { "type": "string" }, "trial_deleted_at": { "type": "string" }, "trial_ended_at": { "type": "string" }, "trial_started_at": { "type": "string" }, "trial_type": { "type": "string" } } }, "subscription.getFeaturesUpsellResponse": { "type": "object", "required": [ "feature_id", "friendly_name", "is_default_feature", "name", "upsell_plan_handle", "upsell_plan_id" ], "properties": { "feature_id": { "type": "integer" }, "friendly_name": { "type": "string" }, "is_default_feature": { "type": "boolean" }, "name": { "type": "string" }, "upsell_plan_handle": { "type": "string", "x-nullable": true }, "upsell_plan_id": { "type": "integer", "x-nullable": true } } }, "subscription.getPlansResponse": { "type": "object", "required": [ "max_user_count", "name", "plan_id", "product_handle" ], "properties": { "max_user_count": { "type": "integer", "x-nullable": true }, "name": { "type": "string" }, "plan_id": { "type": "integer" }, "product_handle": { "type": "string" } } }, "subscription.upsertForcedTrialRequest": { "type": "object", "properties": { "plan_workspace_id": { "type": "integer" } } }, "subscription.upsertForcedTrialResponse": { "type": "object", "required": [ "id", "organization_id", "plan_id", "plan_name", "product_handle", "toggl_product_name", "trial_cancels_at", "trial_created_at", "trial_deleted_at", "trial_ended_at", "trial_started_at", "trial_type" ], "properties": { "id": { "type": "integer" }, "organization_id": { "type": "integer" }, "plan_id": { "type": "integer" }, "plan_name": { "type": "string" }, "product_handle": { "type": "string" }, "toggl_product_name": { "type": "string" }, "trial_cancels_at": { "type": "string" }, "trial_created_at": { "type": "string" }, "trial_deleted_at": { "type": "string" }, "trial_ended_at": { "type": "string" }, "trial_started_at": { "type": "string" }, "trial_type": { "type": "string" } } }, "tag.BulkCreatePayload": { "type": "object", "required": [ "tags" ], "properties": { "tags": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "$ref": "#/definitions/tag.Payload" } } } }, "tag.BulkRestorePayload": { "type": "object", "required": [ "tag_ids" ], "properties": { "tag_ids": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "type": "integer" } } } }, "tag.Payload": { "type": "object", "required": [ "color", "name" ], "properties": { "color": { "type": "string" }, "name": { "type": "string" } } }, "task.BulkArchivePayload": { "type": "object", "required": [ "task_ids" ], "properties": { "task_ids": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "type": "integer" } } } }, "task.BulkCreatePayload": { "type": "object", "required": [ "tasks" ], "properties": { "tasks": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "$ref": "#/definitions/task.CreatePayload" } } } }, "task.BulkDuplicatePayload": { "type": "object", "required": [ "cascade_duplicate_children", "task_ids" ], "properties": { "cascade_duplicate_children": { "type": "boolean" }, "task_ids": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "type": "integer" } } } }, "task.BulkRestorePayload": { "type": "object", "required": [ "task_ids" ], "properties": { "task_ids": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "type": "integer" } } } }, "task.BulkUnarchivePayload": { "type": "object", "required": [ "task_ids" ], "properties": { "task_ids": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "type": "integer" } } } }, "task.CalendarSyncSummary": { "type": "object", "required": [ "changed", "time_blocks_completed", "time_entries_created", "time_entries_materialized", "time_entries_relinked" ], "properties": { "changed": { "type": "integer" }, "time_blocks_completed": { "type": "integer" }, "time_entries_created": { "type": "integer" }, "time_entries_materialized": { "type": "integer" }, "time_entries_relinked": { "type": "integer" } } }, "task.CreatePayload": { "type": "object", "required": [ "name" ], "properties": { "allocation_unit": { "type": "string", "default": "flat", "enum": [ "percent", "flat" ] }, "assignee_user_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "auto_log_time": { "type": "boolean" }, "billable": { "type": "boolean" }, "color": { "type": "string" }, "custom_fields": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" }, "end_date": { "type": "string", "format": "date" }, "estimate_type": { "type": "string", "enum": [ "daily", "total" ] }, "estimated_mins": { "type": "integer" }, "integration_ext_id": { "type": "integer" }, "integration_source": { "type": "string" }, "name": { "type": "string" }, "notes": { "type": "string" }, "parent_task_id": { "type": "integer" }, "pinned": { "type": "boolean" }, "position": { "type": "integer", "x-nullable": true }, "priority": { "type": "string", "enum": [ "none", "low", "medium", "high" ] }, "priority_at": { "type": "string", "format": "date" }, "private": { "type": "boolean" }, "project_id": { "type": "integer" }, "rrule": { "type": "string", "x-nullable": true }, "start_date": { "type": "string", "format": "date" }, "status_id": { "type": "integer" }, "tag_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "team_assignee_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true } } }, "task.CreatePayloadWithoutParentID": { "type": "object", "required": [ "name" ], "properties": { "allocation_unit": { "type": "string", "default": "flat", "enum": [ "percent", "flat" ] }, "assignee_user_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "auto_log_time": { "type": "boolean" }, "billable": { "type": "boolean" }, "color": { "type": "string" }, "custom_fields": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" }, "end_date": { "type": "string", "format": "date" }, "estimate_type": { "type": "string", "enum": [ "daily", "total" ] }, "estimated_mins": { "type": "integer" }, "integration_ext_id": { "type": "integer" }, "integration_source": { "type": "string" }, "name": { "type": "string" }, "notes": { "type": "string" }, "pinned": { "type": "boolean" }, "position": { "type": "integer", "x-nullable": true }, "priority": { "type": "string", "enum": [ "none", "low", "medium", "high" ] }, "priority_at": { "type": "string", "format": "date" }, "private": { "type": "boolean" }, "project_id": { "type": "integer" }, "rrule": { "type": "string", "x-nullable": true }, "start_date": { "type": "string", "format": "date" }, "status_id": { "type": "integer" }, "tag_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "team_assignee_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true } } }, "task.CreateTaskRatePayload": { "type": "object", "required": [ "billable" ], "properties": { "billable": { "type": "boolean" } } }, "task.EventResponse": { "type": "object", "required": [ "all_day", "calendar_id", "end_time", "external_id", "hidden", "ical_uid", "id", "provider", "start_time", "title" ], "properties": { "all_day": { "type": "boolean" }, "background_color": { "type": "string" }, "calendar_id": { "type": "integer" }, "end_time": { "type": "string", "format": "date-time" }, "external_id": { "type": "string" }, "foreground_color": { "type": "string" }, "hidden": { "type": "boolean" }, "html_link": { "type": "string" }, "ical_uid": { "type": "string" }, "id": { "type": "integer" }, "meeting_link": { "type": "string" }, "provider": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "title": { "type": "string" } } }, "task.PartialUpdatePayload": { "type": "object", "properties": { "allocation_unit": { "type": "string", "enum": [ "percent", "flat" ], "x-nullable": true }, "assignee_user_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "auto_log_time": { "type": "boolean", "x-nullable": true }, "billable": { "type": "boolean" }, "color": { "type": "string", "x-nullable": true }, "custom_fields": { "type": "object", "x-nullable": true }, "description": { "type": "string", "x-nullable": true }, "end_date": { "type": "string", "format": "date", "x-nullable": true }, "estimate_type": { "type": "string", "enum": [ "daily", "total" ] }, "estimated_mins": { "type": "integer", "x-nullable": true }, "name": { "type": "string" }, "notes": { "type": "string", "x-nullable": true }, "outbound_sync": { "type": "boolean" }, "parent_task_id": { "type": "integer", "x-nullable": true }, "pinned": { "type": "boolean" }, "position": { "type": "integer", "minimum": 1, "x-nullable": true }, "priority": { "type": "string", "enum": [ "none", "low", "medium", "high" ] }, "priority_at": { "type": "string", "format": "date", "x-nullable": true }, "private": { "type": "boolean" }, "project_id": { "type": "integer", "x-nullable": true }, "recurring_task_id": { "type": "integer", "x-nullable": true }, "rrule": { "type": "string", "x-nullable": true }, "start_date": { "type": "string", "format": "date", "x-nullable": true }, "status_id": { "type": "integer" }, "tag_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "team_assignee_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true } } }, "task.PartialUpdatePayloadWithID": { "type": "object", "required": [ "id" ], "properties": { "allocation_unit": { "type": "string", "enum": [ "percent", "flat" ], "x-nullable": true }, "assignee_user_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "auto_log_time": { "type": "boolean", "x-nullable": true }, "billable": { "type": "boolean" }, "color": { "type": "string", "x-nullable": true }, "custom_fields": { "type": "object", "x-nullable": true }, "description": { "type": "string", "x-nullable": true }, "end_date": { "type": "string", "format": "date", "x-nullable": true }, "estimate_type": { "type": "string", "enum": [ "daily", "total" ] }, "estimated_mins": { "type": "integer", "x-nullable": true }, "id": { "type": "integer" }, "name": { "type": "string" }, "notes": { "type": "string", "x-nullable": true }, "outbound_sync": { "type": "boolean" }, "parent_task_id": { "type": "integer", "x-nullable": true }, "pinned": { "type": "boolean" }, "position": { "type": "integer", "minimum": 1, "x-nullable": true }, "priority": { "type": "string", "enum": [ "none", "low", "medium", "high" ] }, "priority_at": { "type": "string", "format": "date", "x-nullable": true }, "private": { "type": "boolean" }, "project_id": { "type": "integer", "x-nullable": true }, "recurring_task_id": { "type": "integer", "x-nullable": true }, "rrule": { "type": "string", "x-nullable": true }, "start_date": { "type": "string", "format": "date", "x-nullable": true }, "status_id": { "type": "integer" }, "tag_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "team_assignee_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true } } }, "task.PromptPayload": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string" } } }, "task.TaskWithParentAndAggregations": { "type": "object", "required": [ "allocation_unit", "created_at", "estimate_type", "id", "is_template", "name", "pinned", "position", "priority", "private", "source", "status_id", "sub_task_done_count", "sub_task_total_count", "tag_ids", "tags", "time_block_completed_count", "time_block_scheduled_completed_count", "time_block_scheduled_total_count", "time_block_total_count", "time_entry_total_count", "toggl_user_id", "total_blocked_time", "total_scheduled_blocked_time", "total_tracked_time", "workspace_id" ], "properties": { "allocation_unit": { "type": "string", "enum": [ "percent", "flat" ] }, "archived_at": { "type": "string", "format": "date-time" }, "assignee_user_ids": { "type": "array", "items": { "type": "integer" } }, "assignees": { "description": "A unified column for all task entity assignments", "type": "array", "items": { "$ref": "#/definitions/models.TaskAssignment" } }, "auto_log_time": { "type": "boolean" }, "billable": { "type": "boolean" }, "client": { "$ref": "#/definitions/models.ClientLite" }, "color": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "custom_field_values": { "type": "array", "items": { "$ref": "#/definitions/models.CustomFieldValue" } }, "deleted_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "end_date": { "type": "string", "format": "date" }, "estimate_type": { "type": "string", "enum": [ "daily", "total" ] }, "estimated_mins": { "type": "integer" }, "id": { "type": "integer" }, "is_template": { "type": "boolean" }, "metadata": { "$ref": "#/definitions/models.TaskMetadata" }, "name": { "type": "string" }, "notes": { "type": "string" }, "parent": { "$ref": "#/definitions/models.Task" }, "parent_task_id": { "type": "integer" }, "parent_task_name": { "type": "string" }, "pinned": { "type": "boolean" }, "position": { "type": "integer" }, "priority": { "type": "string", "enum": [ "none", "low", "medium", "high" ] }, "priority_at": { "type": "string", "format": "date" }, "private": { "type": "boolean" }, "project": { "$ref": "#/definitions/models.ProjectLite" }, "project_id": { "type": "integer" }, "recurrence_date": { "type": "string", "format": "date" }, "recurring_task_id": { "type": "integer" }, "rrule": { "type": "string" }, "source": { "type": "string" }, "source_template_task_id": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "status": { "$ref": "#/definitions/models.StatusLite" }, "status_id": { "type": "integer" }, "status_updated_at": { "type": "string" }, "sub_task_done_count": { "type": "integer" }, "sub_task_total_count": { "type": "integer" }, "tag_ids": { "type": "array", "items": { "type": "integer" } }, "tags": { "type": "array", "items": { "$ref": "#/definitions/models.TagLite" } }, "time_block_completed_count": { "type": "integer" }, "time_block_scheduled_completed_count": { "type": "integer" }, "time_block_scheduled_total_count": { "type": "integer" }, "time_block_total_count": { "type": "integer" }, "time_entry_total_count": { "type": "integer" }, "toggl_user_id": { "type": "integer" }, "total_blocked_time": { "type": "integer" }, "total_scheduled_blocked_time": { "type": "integer" }, "total_tracked_time": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "task.UpdatePayload": { "type": "object", "required": [ "name", "status_id" ], "properties": { "allocation_unit": { "type": "string", "enum": [ "percent", "flat" ], "x-nullable": true }, "assignee_user_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "auto_log_time": { "type": "boolean" }, "billable": { "type": "boolean" }, "color": { "type": "string" }, "custom_fields": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" }, "end_date": { "type": "string", "format": "date" }, "estimate_type": { "type": "string", "enum": [ "daily", "total" ] }, "estimated_mins": { "type": "integer" }, "name": { "type": "string" }, "notes": { "type": "string" }, "outbound_sync": { "type": "boolean" }, "parent_task_id": { "type": "integer" }, "pinned": { "type": "boolean" }, "position": { "type": "integer", "minimum": 1, "x-nullable": true }, "priority": { "type": "string", "enum": [ "none", "low", "medium", "high" ] }, "private": { "type": "boolean" }, "project_id": { "type": "integer" }, "recurring_task_id": { "type": "integer" }, "rrule": { "type": "string", "x-nullable": true }, "start_date": { "type": "string", "format": "date" }, "status_id": { "type": "integer" }, "tag_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "team_assignee_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true } } }, "taskattachment.Payload": { "type": "object", "required": [ "display_order", "name" ], "properties": { "display_order": { "type": "integer" }, "name": { "type": "string" } } }, "taskconstraints.RequiredField": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "$ref": "#/definitions/taskconstraints.RequiredFieldKind" } } }, "taskconstraints.RequiredFieldKind": { "type": "string", "enum": [ "project", "description", "tags" ], "x-enum-varnames": [ "RequiredFieldKindProject", "RequiredFieldKindDescription", "RequiredFieldKindTags" ] }, "taskconstraints.Response": { "type": "object", "required": [ "created_at", "enabled", "enabled_at", "required_fields", "updated_at", "workspace_id" ], "properties": { "created_at": { "type": "string" }, "enabled": { "type": "boolean" }, "enabled_at": { "type": "string" }, "required_fields": { "type": "array", "items": { "$ref": "#/definitions/taskconstraints.RequiredField" } }, "updated_at": { "type": "string" }, "workspace_id": { "type": "integer" } } }, "taskconstraints.UpsertPayload": { "type": "object", "required": [ "enabled", "required_fields" ], "properties": { "enabled": { "type": "boolean" }, "required_fields": { "type": "array", "items": { "$ref": "#/definitions/taskconstraints.RequiredField" } } } }, "taskestimateallocation.AllocationValues": { "type": "object", "required": [ "toggl_user_id" ], "properties": { "allocated_mins": { "type": "integer", "minimum": 0 }, "allocated_percent": { "type": "integer", "maximum": 10000, "minimum": 0 }, "toggl_user_id": { "type": "integer" } } }, "taskestimateallocation.UpdatePayload": { "type": "object", "required": [ "id" ], "properties": { "allocated_mins": { "type": "integer", "minimum": 0, "x-nullable": true }, "allocated_percent": { "type": "integer", "maximum": 10000, "minimum": 0, "x-nullable": true }, "id": { "type": "integer" } } }, "taskgroup.UpdateTaskGroupEntryParams": { "type": "object", "required": [ "id", "op", "target_group_id", "weight" ], "properties": { "end_date": { "type": "string", "format": "date" }, "id": { "type": "integer" }, "op": { "type": "string", "enum": [ "move", "remove" ] }, "source_group_id": { "type": "integer", "x-nullable": true }, "start_date": { "type": "string", "format": "date" }, "target_group_id": { "description": "An explicit null target on a users-dimension move lands the task in\nthe no-assignee bucket (the id=0 group on reads) and enforces the\nbucket invariant regardless of the source — the dates follow the\ndrop, direct user assignees and team assignments are cleared (a\nno-op for a task already inside the bucket, so repositions work\nunchanged). Clearing\ncannot depend on the source because an external drop (the\nunplanned-tasks tray) arrives without a source row. Omitting the\nproperty on a move is rejected, so it is spec-required yet nullable.\nMoves in every other dimension require a real target — enforced in\nthe handler, where the dimension is known.", "type": "integer", "x-nullable": true }, "weight": { "type": "integer", "minimum": 0 } } }, "taskgroup.taskGroupsResponse": { "type": "object", "required": [ "data", "page", "per_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.TaskGroup" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "tasksuggestion.suggestBulkPayload": { "type": "object", "required": [ "task_ids" ], "properties": { "task_ids": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "type": "integer" } } } }, "tasksuggestion.suggestPayload": { "type": "object", "required": [ "task_id" ], "properties": { "task_id": { "type": "integer" } } }, "tasksuggestion.suggestionDetail": { "type": "object", "required": [ "accuracy", "match_tier", "matched_name", "normalized_name", "project_id" ], "properties": { "accuracy": { "type": "number" }, "match_tier": { "type": "string" }, "matched_name": { "type": "string" }, "normalized_name": { "type": "string" }, "project_id": { "type": "integer" } } }, "tasksuggestion.suggestionResponse": { "type": "object", "required": [ "reason", "suggestion", "task_id" ], "properties": { "reason": { "type": "string" }, "suggestion": { "$ref": "#/definitions/tasksuggestion.suggestionDetail" }, "task_id": { "type": "integer" } } }, "tasksuggestion.timeLogSuggestionBulkItem": { "type": "object", "required": [ "key", "title" ], "properties": { "key": { "type": "string" }, "title": { "type": "string" } } }, "tasksuggestion.timeLogSuggestionBulkItemResponse": { "type": "object", "required": [ "key", "reason", "suggestion" ], "properties": { "key": { "type": "string" }, "reason": { "type": "string", "x-nullable": true }, "suggestion": { "allOf": [ { "$ref": "#/definitions/tasksuggestion.timeLogSuggestionDetail" } ], "x-nullable": true } } }, "tasksuggestion.timeLogSuggestionBulkRequest": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "$ref": "#/definitions/tasksuggestion.timeLogSuggestionBulkItem" } } } }, "tasksuggestion.timeLogSuggestionDetail": { "type": "object", "required": [ "accuracy", "match_tier", "project_id", "task_id" ], "properties": { "accuracy": { "type": "number" }, "match_tier": { "type": "string" }, "project_id": { "type": "integer", "x-nullable": true }, "task_id": { "type": "integer", "x-nullable": true } } }, "tasksuggestion.timeLogSuggestionRequest": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" } } }, "tasksuggestion.timeLogSuggestionResponse": { "type": "object", "required": [ "reason", "suggestion" ], "properties": { "reason": { "type": "string", "x-nullable": true }, "suggestion": { "allOf": [ { "$ref": "#/definitions/tasksuggestion.timeLogSuggestionDetail" } ], "x-nullable": true } } }, "timeblock.BulkCreatePayload": { "type": "object", "required": [ "time_blocks" ], "properties": { "time_blocks": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/timeblock.PayloadWithTaskID" } } } }, "timeblock.PartialUpdatePayload": { "type": "object", "properties": { "completed": { "type": "boolean" }, "duration": { "type": "integer", "minimum": 0 }, "outbound_sync": { "type": "boolean" }, "start": { "type": "string", "format": "date-time" }, "task_id": { "type": "integer" } } }, "timeblock.PartialUpdatePayloadWithID": { "type": "object", "required": [ "id" ], "properties": { "completed": { "type": "boolean" }, "duration": { "type": "integer", "minimum": 0 }, "id": { "type": "integer" }, "outbound_sync": { "type": "boolean" }, "start": { "type": "string", "format": "date-time" }, "task_id": { "type": "integer" } } }, "timeblock.Payload": { "type": "object", "required": [ "start" ], "properties": { "completed": { "type": "boolean" }, "duration": { "type": "integer", "minimum": 0 }, "outbound_sync": { "type": "boolean" }, "start": { "type": "string" } } }, "timeblock.PayloadWithTaskID": { "type": "object", "required": [ "start", "task_id" ], "properties": { "completed": { "type": "boolean" }, "duration": { "type": "integer", "minimum": 0 }, "outbound_sync": { "type": "boolean" }, "start": { "type": "string" }, "task_id": { "type": "integer" } } }, "timeblock.TimeBlockAggregate": { "type": "object", "required": [ "created_at", "has_time_entry", "id", "start", "task_id", "toggl_user_id", "workspace_id" ], "properties": { "archived_at": { "type": "string", "format": "date-time" }, "calendar_event_id": { "type": "integer" }, "completed_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "duration": { "type": "integer" }, "has_time_entry": { "type": "boolean" }, "id": { "type": "integer" }, "start": { "type": "string", "format": "date-time" }, "task_id": { "type": "integer" }, "timezone": { "description": "Timezone is the effective IANA timezone hydrated on reads: the workspace timezone\nsnapshotted at creation when set, else the creator's snapshot; NULL when unresolved.", "type": "string" }, "toggl_user_id": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "timeblock.TimeBlockAggregateWithTask": { "type": "object", "required": [ "created_at", "has_time_entry", "id", "start", "task_id", "toggl_user_id", "workspace_id" ], "properties": { "archived_at": { "type": "string", "format": "date-time" }, "calendar_event_id": { "type": "integer" }, "completed_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "duration": { "type": "integer" }, "has_time_entry": { "type": "boolean" }, "id": { "type": "integer" }, "start": { "type": "string", "format": "date-time" }, "task": { "$ref": "#/definitions/models.Task" }, "task_id": { "type": "integer" }, "timezone": { "description": "Timezone is the effective IANA timezone hydrated on reads: the workspace timezone\nsnapshotted at creation when set, else the creator's snapshot; NULL when unresolved.", "type": "string" }, "toggl_user_id": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "timeentry.BulkCreatePayload": { "type": "object", "required": [ "type" ], "properties": { "billable": { "type": "boolean" }, "calendar_event_id": { "type": "integer" }, "description": { "type": "string" }, "duration": { "type": "integer", "minimum": 0 }, "planned_at": { "type": "string", "format": "date-time" }, "planned_duration": { "type": "integer", "minimum": 0 }, "planned_start": { "type": "string", "format": "date-time" }, "project_id": { "type": "integer" }, "start": { "type": "string", "format": "date-time" }, "tag_ids": { "description": "TagIDs sets a manual tag override at creation (entry-authoritative,\nincluding an explicit empty array). Absent/null = no override: the\nentry inherits the linked task's tags.", "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "task_id": { "type": "integer" }, "time_block_id": { "type": "integer" }, "tracked_at": { "type": "string", "format": "date-time" }, "type": { "description": "The type of time entry. This could either be an activity, or a break.", "enum": [ "activity", "break" ], "allOf": [ { "$ref": "#/definitions/models.TimeEntryType" } ] }, "user_id": { "type": "integer" } } }, "timeentry.BulkEditPayload": { "type": "object", "required": [ "changes", "ids" ], "properties": { "changes": { "$ref": "#/definitions/timeentry.PartialUpdatePayload" }, "ids": { "description": "min=1 is not redundant with required: a decoded `[]` is non-nil, so\nrequired alone would let an empty id list through.", "type": "array", "minItems": 1, "items": { "type": "integer" } } } }, "timeentry.CalendarEvent": { "type": "object", "required": [ "all_day", "background_color", "end_time", "foreground_color", "html_link", "id", "meeting_link", "provider", "start_time", "title" ], "properties": { "all_day": { "type": "boolean" }, "background_color": { "type": "string", "x-nullable": true }, "end_time": { "type": "string" }, "foreground_color": { "type": "string", "x-nullable": true }, "html_link": { "type": "string" }, "id": { "type": "integer" }, "meeting_link": { "type": "string", "x-nullable": true }, "provider": { "type": "string" }, "start_time": { "type": "string" }, "title": { "type": "string" } } }, "timeentry.CreatePayload": { "type": "object", "required": [ "type" ], "properties": { "billable": { "type": "boolean" }, "calendar_event_id": { "type": "integer" }, "description": { "type": "string" }, "duration": { "type": "integer", "minimum": 0 }, "planned_at": { "type": "string", "format": "date-time" }, "planned_duration": { "type": "integer", "minimum": 0 }, "planned_start": { "type": "string", "format": "date-time" }, "project_id": { "type": "integer" }, "start": { "type": "string", "format": "date-time" }, "tag_ids": { "description": "TagIDs sets a manual tag override at creation (entry-authoritative,\nincluding an explicit empty array). Absent/null = no override: the\nentry inherits the linked task's tags.", "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "time_block_id": { "type": "integer" }, "tracked_at": { "type": "string", "format": "date-time" }, "type": { "description": "The type of time entry. This could either be an activity, or a break.", "enum": [ "activity", "break" ], "allOf": [ { "$ref": "#/definitions/models.TimeEntryType" } ] }, "user_id": { "type": "integer" } } }, "timeentry.CreateTasklessPayload": { "type": "object", "required": [ "type" ], "properties": { "billable": { "type": "boolean" }, "calendar_event_id": { "type": "integer" }, "description": { "type": "string" }, "duration": { "type": "integer", "minimum": 0 }, "planned_at": { "type": "string", "format": "date-time" }, "planned_duration": { "type": "integer", "minimum": 0 }, "planned_start": { "type": "string", "format": "date-time" }, "project_id": { "type": "integer" }, "start": { "type": "string", "format": "date-time" }, "tag_ids": { "description": "TagIDs sets a manual tag override at creation (entry-authoritative,\nincluding an explicit empty array). Absent/null = no override: the\nentry inherits the linked task's tags.", "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "time_block_id": { "type": "integer" }, "tracked_at": { "type": "string", "format": "date-time" }, "type": { "description": "The type of time entry. This could either be an activity, or a break.", "enum": [ "activity", "break" ], "allOf": [ { "$ref": "#/definitions/models.TimeEntryType" } ] }, "user_id": { "type": "integer" } } }, "timeentry.DayDurationDiscriminant": { "type": "object", "properties": { "billable": { "type": "boolean" }, "description": { "type": "string", "x-nullable": true }, "project_id": { "type": "integer", "x-nullable": true }, "tag_ids": { "description": "TagIDs scopes the row to a single effective active tag set (entry\noverride, else task tags, else empty; soft-deleted tags excluded),\ncompared order-insensitively. Absent/null applies no tag constraint,\npreserving the pre-tag behavior.", "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "task_id": { "type": "integer", "x-nullable": true } } }, "timeentry.PartialUpdatePayload": { "type": "object", "properties": { "billable": { "type": "boolean" }, "description": { "type": "string", "x-nullable": true }, "duration": { "type": "integer", "minimum": 0 }, "planned_at": { "type": "string", "format": "date-time", "x-nullable": true }, "planned_duration": { "type": "integer", "minimum": 0, "x-nullable": true }, "planned_start": { "type": "string", "format": "date-time", "x-nullable": true }, "project_id": { "type": "integer", "x-nullable": true }, "reset_billable_to_default": { "type": "boolean" }, "start": { "type": "string", "format": "date-time", "x-nullable": true }, "tag_ids": { "description": "TagIDs is tri-state: absent leaves the stored override untouched;\nexplicit null clears the override (reset to task inheritance); an\narray (including empty) sets a manual, entry-authoritative override.", "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "task_id": { "type": "integer", "x-nullable": true }, "time_block_id": { "type": "integer", "x-nullable": true }, "tracked_at": { "type": "string", "format": "date-time", "x-nullable": true }, "type": { "type": "string", "enum": [ "activity", "break" ] } } }, "timeentry.PartialUpdatePayloadWithID": { "type": "object", "required": [ "id" ], "properties": { "billable": { "type": "boolean" }, "description": { "type": "string", "x-nullable": true }, "duration": { "type": "integer", "minimum": 0 }, "id": { "type": "integer" }, "planned_at": { "type": "string", "format": "date-time", "x-nullable": true }, "planned_duration": { "type": "integer", "minimum": 0, "x-nullable": true }, "planned_start": { "type": "string", "format": "date-time", "x-nullable": true }, "project_id": { "type": "integer", "x-nullable": true }, "reset_billable_to_default": { "type": "boolean" }, "start": { "type": "string", "format": "date-time", "x-nullable": true }, "tag_ids": { "description": "TagIDs is tri-state: absent leaves the stored override untouched;\nexplicit null clears the override (reset to task inheritance); an\narray (including empty) sets a manual, entry-authoritative override.", "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "task_id": { "type": "integer", "x-nullable": true }, "time_block_id": { "type": "integer", "x-nullable": true }, "tracked_at": { "type": "string", "format": "date-time", "x-nullable": true }, "type": { "type": "string", "enum": [ "activity", "break" ] } } }, "timeentry.Payload": { "type": "object", "required": [ "type" ], "properties": { "calendar_event_id": { "type": "integer" }, "description": { "type": "string" }, "duration": { "type": "integer", "minimum": 0 }, "planned_at": { "type": "string", "format": "date-time" }, "planned_duration": { "type": "integer", "minimum": 0 }, "planned_start": { "type": "string", "format": "date-time" }, "start": { "type": "string", "format": "date-time" }, "tag_ids": { "description": "TagIDs sets a manual tag override at creation (entry-authoritative,\nincluding an explicit empty array). Absent/null = no override: the\nentry inherits the linked task's tags.", "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "time_block_id": { "type": "integer" }, "tracked_at": { "type": "string", "format": "date-time" }, "type": { "description": "The type of time entry. This could either be an activity, or a break.", "enum": [ "activity", "break" ], "allOf": [ { "$ref": "#/definitions/models.TimeEntryType" } ] } } }, "timeentry.SetDayDurationPayload": { "type": "object", "required": [ "date_from", "date_to", "duration" ], "properties": { "date_from": { "type": "string", "format": "date-time" }, "date_to": { "type": "string", "format": "date-time" }, "discriminant": { "$ref": "#/definitions/timeentry.DayDurationDiscriminant" }, "duration": { "type": "integer", "minimum": 0 }, "start_time": { "type": "string", "format": "date-time" }, "task_id": { "description": "Deprecated: prefer Discriminant. Kept for backward compatibility.", "type": "integer" } } }, "timeentry.StartTrackingPayload": { "type": "object", "required": [ "type" ], "properties": { "billable": { "type": "boolean" }, "calendar_event_id": { "type": "integer" }, "description": { "type": "string" }, "project_id": { "type": "integer" }, "start": { "type": "string", "format": "date-time" }, "tag_ids": { "description": "TagIDs sets a manual tag override on the started entry; absent/null\ninherits the task's tags.", "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "task_id": { "type": "integer" }, "time_block_id": { "type": "integer" }, "type": { "$ref": "#/definitions/models.TimeEntryType" } } }, "timeentry.StopTrackingPayload": { "type": "object", "required": [ "end" ], "properties": { "end": { "type": "string", "format": "date-time" } } }, "timeentry.TimeEntryWithTask": { "type": "object", "required": [ "created_at", "id", "toggl_user_id", "type", "workspace_id" ], "properties": { "archived_at": { "type": "string", "format": "date-time" }, "billable": { "type": "boolean" }, "billable_source": { "enum": [ "manual", "task_default" ], "allOf": [ { "$ref": "#/definitions/models.BillableSource" } ] }, "calendar_event": { "allOf": [ { "$ref": "#/definitions/timeentry.CalendarEvent" } ], "x-nullable": true }, "calendar_event_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "duration": { "type": "integer" }, "id": { "type": "integer" }, "planned_at": { "type": "string", "format": "date-time" }, "planned_duration": { "type": "integer" }, "planned_start": { "type": "string", "format": "date-time" }, "project": { "$ref": "#/definitions/models.ProjectLite" }, "project_id": { "type": "integer" }, "start": { "type": "string", "format": "date-time" }, "tag_ids": { "description": "TagIDs is the entry's manual tag override. NULL (nil) means no override:\nthe effective tags fall through to the linked task's tags. A non-nil\nvalue — including an empty array — is entry-authoritative.", "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "tags": { "description": "Tags is the hydrated effective tag set: the override when TagIDs is set,\nelse the linked task's active tags. Read-only.", "type": "array", "items": { "$ref": "#/definitions/models.TagLite" } }, "task": { "$ref": "#/definitions/models.Task" }, "task_id": { "type": "integer", "x-nullable": true }, "time_block_id": { "type": "integer" }, "timezone": { "description": "Timezone is the effective IANA timezone hydrated on reads: the workspace timezone\nsnapshotted at creation when set, else the creator's snapshot; NULL when unresolved.", "type": "string" }, "toggl_user_id": { "type": "integer" }, "tracked_at": { "type": "string", "format": "date-time" }, "type": { "description": "The type of time entry: either an activity or a break.", "enum": [ "activity", "break" ], "allOf": [ { "$ref": "#/definitions/models.TimeEntryType" } ] }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "timeentryconstraints.BulkFailureValue": { "type": "object", "required": [ "fields", "is_deletion", "time_entry_index" ], "properties": { "fields": { "type": "array", "items": { "type": "string" } }, "is_deletion": { "type": "boolean" }, "time_entry_index": { "type": "integer" } } }, "timeentryconstraints.BulkRequiredFieldsErrorResponse": { "type": "object", "required": [ "error", "error_description", "error_values" ], "properties": { "error": { "enum": [ "bulk_required_fields_missing" ], "allOf": [ { "$ref": "#/definitions/timeentryconstraints.RequiredFieldsErrorCode" } ], "example": "bulk_required_fields_missing" }, "error_description": { "type": "string" }, "error_values": { "$ref": "#/definitions/timeentryconstraints.BulkRequiredFieldsErrorValues" } } }, "timeentryconstraints.BulkRequiredFieldsErrorValues": { "type": "object", "required": [ "failures" ], "properties": { "failures": { "type": "array", "items": { "$ref": "#/definitions/timeentryconstraints.BulkFailureValue" } } } }, "timeentryconstraints.RequiredField": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "$ref": "#/definitions/timeentryconstraints.RequiredFieldKind" } } }, "timeentryconstraints.RequiredFieldKind": { "type": "string", "enum": [ "project", "task", "description" ], "x-enum-varnames": [ "RequiredFieldKindProject", "RequiredFieldKindTask", "RequiredFieldKindDescription" ] }, "timeentryconstraints.RequiredFieldsErrorCode": { "type": "string", "enum": [ "required_fields_missing", "required_fields_deletion", "bulk_required_fields_missing" ], "x-enum-varnames": [ "ErrCodeRequiredFieldsMissing", "ErrCodeRequiredFieldsDeletion", "ErrCodeBulkRequiredFieldsMissing" ] }, "timeentryconstraints.RequiredFieldsErrorResponse": { "type": "object", "required": [ "error", "error_description", "error_values" ], "properties": { "error": { "enum": [ "required_fields_missing", "required_fields_deletion" ], "allOf": [ { "$ref": "#/definitions/timeentryconstraints.RequiredFieldsErrorCode" } ], "example": "required_fields_missing" }, "error_description": { "type": "string" }, "error_values": { "$ref": "#/definitions/timeentryconstraints.RequiredFieldsErrorValues" } } }, "timeentryconstraints.RequiredFieldsErrorValues": { "type": "object", "required": [ "fields", "is_deletion" ], "properties": { "fields": { "type": "array", "items": { "type": "string" } }, "is_deletion": { "type": "boolean" } } }, "timeentryconstraints.Response": { "type": "object", "required": [ "created_at", "disallow_billable_override", "enabled", "enabled_at", "required_fields", "updated_at", "workspace_id" ], "properties": { "created_at": { "type": "string", "format": "date-time", "x-nullable": true }, "disallow_billable_override": { "type": "boolean" }, "enabled": { "type": "boolean" }, "enabled_at": { "description": "EnabledAt, CreatedAt, UpdatedAt are always present as JSON keys but null when\nno row exists for the workspace (or, for EnabledAt, when constraints are disabled).\nPer the API contract (issue toggl/bizops-team#39) and the OpenAPI schema.", "type": "string", "format": "date-time", "x-nullable": true }, "required_fields": { "type": "array", "items": { "$ref": "#/definitions/timeentryconstraints.RequiredField" } }, "updated_at": { "type": "string", "format": "date-time", "x-nullable": true }, "workspace_id": { "type": "integer" } } }, "timeentryconstraints.UpsertPayload": { "type": "object", "required": [ "enabled", "required_fields" ], "properties": { "disallow_billable_override": { "type": "boolean" }, "enabled": { "type": "boolean" }, "required_fields": { "type": "array", "items": { "$ref": "#/definitions/timeentryconstraints.RequiredField" } } } }, "timeoff.TimeOff": { "type": "object", "required": [ "created_at", "end_time", "organization_id", "start_time", "timeoff_id", "updated_at", "user_id" ], "properties": { "created_at": { "description": "CreatedAt is the RFC3339 timestamp (UTC) the entry was created at.", "type": "string" }, "end_time": { "description": "EndTime is the RFC3339 timestamp (UTC) the time off period ends at; always after StartTime.", "type": "string" }, "organization_id": { "description": "OrganizationID is the organization the entry belongs to.", "type": "integer" }, "start_time": { "description": "StartTime is the RFC3339 timestamp (UTC) the time off period starts at.", "type": "string" }, "timeoff_id": { "description": "ID is the unique identifier of the time off entry.", "type": "integer" }, "type": { "description": "Type is the category of the time off: vacation, sick, parental or other. Omitted when the entry has no category.", "type": "string" }, "updated_at": { "description": "UpdatedAt is the RFC3339 timestamp (UTC) the entry was last modified at.", "type": "string" }, "user_id": { "description": "UserID is the user the time off was booked for.", "type": "integer" } } }, "timeoff.TimeOffBatchCreateInput": { "type": "object", "required": [ "end_time", "start_time" ], "properties": { "end_time": { "description": "EndTime is the RFC3339 timestamp the time off period ends at; must be after StartTime. Send it in UTC: offsets are discarded, not converted.", "type": "string" }, "start_time": { "description": "StartTime is the RFC3339 timestamp the time off period starts at. Send it in UTC: offsets are discarded, not converted.", "type": "string" }, "type": { "description": "Type is the optional category of the time off: vacation, sick, parental or other. Omit to leave the entry uncategorized.", "type": "string", "enum": [ "vacation", "sick", "parental", "other" ] } } }, "timeoff.TimeOffBatchUpdateInput": { "type": "object", "required": [ "end_time", "start_time", "timeoff_id" ], "properties": { "end_time": { "description": "EndTime is the RFC3339 timestamp the time off period ends at; must be after StartTime. Send it in UTC: offsets are discarded, not converted.", "type": "string" }, "start_time": { "description": "StartTime is the RFC3339 timestamp the time off period starts at. Send it in UTC: offsets are discarded, not converted.", "type": "string" }, "timeoff_id": { "description": "ID is the unique identifier of the time off entry to update.", "type": "integer" }, "type": { "description": "Type is the optional category of the time off: vacation, sick, parental or other. Omitting it clears the entry's stored category.", "type": "string", "enum": [ "vacation", "sick", "parental", "other" ] } } }, "timesheet.AddFlagPayload": { "type": "object", "required": [ "comment", "time_entry_id" ], "properties": { "comment": { "type": "string", "maxLength": 1000 }, "time_entry_id": { "type": "integer" } } }, "timesheet.ApproverRef": { "type": "object", "required": [ "name", "user_account_id" ], "properties": { "name": { "description": "Name is the approver's display name, resolved from their account\nprofile at query time.", "type": "string" }, "user_account_id": { "description": "UserAccountID identifies the approver.", "type": "integer" } } }, "timesheet.BulkApprovePayload": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "$ref": "#/definitions/timesheet.BulkKeyPayload" } } } }, "timesheet.BulkFailure": { "type": "object", "required": [ "code", "key", "reason" ], "properties": { "code": { "description": "Code is the machine-readable error code, matching the codes\nproduced by HandleErrorResponse for the same underlying\nerror.", "type": "string" }, "key": { "description": "Key is the input key that failed.", "allOf": [ { "$ref": "#/definitions/timesheet.Key" } ] }, "reason": { "description": "Reason is a human-readable error message.", "type": "string" } } }, "timesheet.BulkKeyPayload": { "type": "object", "required": [ "setup_id", "start_date", "user_account_id" ], "properties": { "setup_id": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "user_account_id": { "type": "integer" } } }, "timesheet.BulkRequestChangesPayload": { "type": "object", "required": [ "keys" ], "properties": { "comment": { "type": "string", "maxLength": 1000 }, "keys": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "$ref": "#/definitions/timesheet.BulkKeyPayload" } } } }, "timesheet.BulkResult": { "type": "object", "required": [ "failed", "succeeded" ], "properties": { "failed": { "description": "Failed lists the keys whose action did not, with reasons.", "type": "array", "items": { "$ref": "#/definitions/timesheet.BulkFailure" } }, "succeeded": { "description": "Succeeded lists the keys whose action completed.", "type": "array", "items": { "$ref": "#/definitions/timesheet.Key" } } } }, "timesheet.BulkWithdrawPayload": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "$ref": "#/definitions/timesheet.BulkKeyPayload" } } } }, "timesheet.CommentPayload": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "string", "maxLength": 1000 } } }, "timesheet.Details": { "type": "object", "required": [ "approvers", "flags", "hours", "member", "setup", "time_entries", "timesheet" ], "properties": { "approvers": { "description": "Approvers is the ordered approval chain at query time.", "type": "array", "items": { "$ref": "#/definitions/models.TimesheetSetupApprover" } }, "flags": { "description": "Flags are the active flags on those entries.", "type": "array", "items": { "$ref": "#/definitions/models.TimesheetFlag" } }, "hours": { "description": "Hours is the computed hours summary for the period.", "allOf": [ { "$ref": "#/definitions/timesheet.HoursSummary" } ] }, "member": { "description": "Member is the snapshotted member info (name, email,\ntimezone).", "allOf": [ { "$ref": "#/definitions/timesheet.MemberInfo" } ] }, "setup": { "description": "Setup is the parent setup at query time.", "allOf": [ { "$ref": "#/definitions/models.TimesheetSetup" } ] }, "time_entries": { "description": "TimeEntries are the entries whose start falls in the period\n(in the member's timezone), matching what is counted and what\ncan be flagged - not every entry overlapping the window. Each is\nenriched with its task (name, tags) and project (name, color,\nclient) so the detail view renders without extra lookups.", "type": "array", "items": { "$ref": "#/definitions/timeentry.TimeEntryWithTask" } }, "timesheet": { "description": "Timesheet is the underlying record.", "allOf": [ { "$ref": "#/definitions/models.Timesheet" } ] } } }, "timesheet.HoursSummary": { "type": "object", "required": [ "billable_minutes", "billable_percent", "expected_minutes", "logged_minutes", "planned_minutes", "total_minutes" ], "properties": { "billable_minutes": { "description": "BillableMinutes is the sum of durations on entries marked\nbillable.", "type": "integer" }, "billable_percent": { "description": "BillablePercent is BillableMinutes / TotalMinutes * 100,\nrounded to one decimal place. Zero when TotalMinutes is\nzero.", "type": "number" }, "expected_minutes": { "description": "ExpectedMinutes is the working capacity for the period,\nsourced from the capacity service.", "type": "integer" }, "logged_minutes": { "description": "LoggedMinutes equals TotalMinutes; kept as a separate field\nso the planned-vs-logged comparison is self-documenting at\nthe call site.", "type": "integer" }, "planned_minutes": { "description": "PlannedMinutes is the sum of time block durations planned\nfor the period.", "type": "integer" }, "total_minutes": { "description": "TotalMinutes is the sum of logged time entry durations.", "type": "integer" } } }, "timesheet.Key": { "type": "object", "required": [ "setup_id", "start_date", "user_account_id" ], "properties": { "setup_id": { "description": "SetupID identifies the parent timesheet setup.", "type": "integer" }, "start_date": { "description": "StartDate is the inclusive start of the period and must\nalign with the setup's anchor + periodicity.", "type": "string", "format": "date" }, "user_account_id": { "description": "UserAccountID identifies the member whose timesheet is\nbeing addressed (not the actor performing the action).", "type": "integer" } } }, "timesheet.MemberInfo": { "type": "object", "required": [ "email", "name", "timezone", "user_account_id" ], "properties": { "email": { "description": "Email is the member's email address, resolved from their account\nprofile at query time. Not persisted with the timesheet.", "type": "string" }, "name": { "description": "Name is the member's display name, resolved from their account\nprofile at query time. Not persisted with the timesheet, so it\nalways reflects the member's current name.", "type": "string" }, "timezone": { "description": "Timezone is the IANA timezone snapshotted at submission and\nread back from Timesheet.SubmitterTimezone.", "type": "string" }, "user_account_id": { "description": "UserAccountID identifies the member.", "type": "integer" } } }, "timesheet.ReviewRef": { "type": "object", "required": [ "action", "created_at", "name", "user_account_id" ], "properties": { "action": { "description": "Action is the review action taken.", "allOf": [ { "$ref": "#/definitions/models.TimesheetReviewAction" } ] }, "created_at": { "description": "CreatedAt is when the action was taken.", "type": "string", "format": "date-time" }, "name": { "description": "Name is the actor's display name, resolved from their account\nprofile at query time.", "type": "string" }, "user_account_id": { "description": "UserAccountID is the actor who performed the action.", "type": "integer" } } }, "timesheet.Summary": { "type": "object", "required": [ "approvers", "capacity_minutes", "flag_count", "logged_minutes", "member_name", "reviews", "timesheet" ], "properties": { "approvers": { "description": "Approvers are the approvers responsible for reviewing this\ntimesheet: the setup's configured approvers at the timesheet's\ncurrent layer. Always populated.", "type": "array", "items": { "$ref": "#/definitions/timesheet.ApproverRef" } }, "capacity_minutes": { "description": "CapacityMinutes is the member's working-capacity minutes for the\nperiod — the expected hours LoggedMinutes is measured against.", "type": "integer" }, "flag_count": { "description": "FlagCount is the number of active flags on this timesheet.", "type": "integer" }, "logged_minutes": { "description": "LoggedMinutes is the sum of durations for entries whose start\nfalls in the period (in the member's timezone); an entry that\noverlaps but starts in an adjacent period is not counted here.", "type": "integer" }, "member_name": { "description": "MemberName is the member's display name, resolved from their\naccount profile at query time. Not persisted with the timesheet,\nso it always reflects the member's current name.", "type": "string" }, "reviews": { "description": "Reviews is the name-resolved review trail (actor, action, time),\noldest first, so the most recent entry is who last acted on the\ntimesheet. Empty for virtual rows.", "type": "array", "items": { "$ref": "#/definitions/timesheet.ReviewRef" } }, "timesheet": { "description": "Timesheet is the underlying record (virtual or persisted).", "allOf": [ { "$ref": "#/definitions/models.Timesheet" } ] } } }, "timesheetsetup.ApproverLayerPayload": { "type": "object", "required": [ "layer", "user_account_ids" ], "properties": { "layer": { "type": "integer", "minimum": 0 }, "user_account_ids": { "type": "array", "minItems": 1, "items": { "type": "integer" } } } }, "timesheetsetup.CreatePayload": { "type": "object", "required": [ "approvers", "member_user_account_ids", "periodicity", "start_date" ], "properties": { "approvers": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/timesheetsetup.ApproverLayerPayload" } }, "email_reminder_enabled": { "type": "boolean" }, "member_user_account_ids": { "type": "array", "minItems": 1, "items": { "type": "integer" } }, "period_days": { "type": "integer", "minimum": 1 }, "periodicity": { "enum": [ "weekly" ], "allOf": [ { "$ref": "#/definitions/models.Periodicity" } ] }, "reminder_day": { "type": "integer" }, "reminder_time": { "type": "string", "example": "09:00" }, "start_date": { "type": "string", "format": "date" } } }, "timesheetsetup.DiscontinuePayload": { "type": "object", "required": [ "end_date" ], "properties": { "end_date": { "type": "string", "format": "date" } } }, "timesheetsetup.MemberDiscontinuePayload": { "type": "object", "properties": { "end_date": { "type": "string", "format": "date" } } }, "timesheetsetup.ReminderPayload": { "type": "object", "required": [ "day", "time" ], "properties": { "day": { "type": "integer", "minimum": 0 }, "time": { "type": "string", "example": "09:00" } } }, "timesheetsetup.UpdatePayload": { "type": "object", "properties": { "approvers": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/timesheetsetup.ApproverLayerPayload" } }, "email_reminder_enabled": { "type": "boolean" }, "member_user_account_ids": { "type": "array", "minItems": 1, "items": { "type": "integer" } }, "reminder": { "$ref": "#/definitions/timesheetsetup.ReminderPayload" }, "unset_reminder": { "type": "boolean" } } }, "types.Permission": { "type": "object", "required": [ "category_id", "category_name", "condition", "description", "entity", "name", "permission_id" ], "properties": { "category_id": { "type": "integer" }, "category_name": { "type": "string" }, "condition": { "type": "string" }, "description": { "type": "string" }, "entity": { "type": "string", "enum": [ "organization", "workspace", "project", "group" ] }, "name": { "type": "string" }, "permission_id": { "type": "integer" } } }, "types.Role": { "type": "object", "required": [ "code", "default_for_levels", "description", "entity", "name", "organization_id", "permissions", "privilege_level", "require_group", "role_id", "type" ], "properties": { "code": { "type": "string" }, "default_for_levels": { "description": "DefaultForLevels lists every level this role is the default at, and is nil when it is not\none — never an empty list, which the stored column rejects.", "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "entity": { "type": "string", "enum": [ "organization", "workspace", "project", "group" ] }, "name": { "type": "string" }, "organization_id": { "type": "integer" }, "permissions": { "type": "array", "items": { "$ref": "#/definitions/types.Permission" } }, "privilege_level": { "type": "integer" }, "require_group": { "description": "RequireGroup is true when the role is only conferred through a group, whatever Entity says.\nIts permissions still cover Entity — a team role's cover the workspace — so a caller listing\nthe roles assignable directly at an entity has to drop the ones that carry it, while a\ncaller listing what a team can confer does not.", "type": "boolean" }, "role_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "owner", "admin", "manager", "guest" ] } } }, "user.PartialUpdatePayload": { "type": "object", "properties": { "attachments_display_mode": { "type": "string", "enum": [ "list", "grid" ], "x-nullable": true }, "autocomplete_task_with_time_block": { "type": "boolean" }, "autolog_time": { "type": "boolean" }, "calendar_future_defaults_to_plan": { "type": "boolean" }, "calendar_project_suggestion_fallback": { "type": "boolean" }, "calendar_range_type": { "type": "string", "x-nullable": true }, "calendar_show_calendar_events": { "type": "boolean" }, "calendar_show_completed_tasks": { "type": "boolean" }, "calendar_show_tasks_list": { "type": "boolean" }, "calendar_split_view_columns": { "type": "string", "x-nullable": true }, "calendar_task_creation_behavior": { "type": "string", "enum": [ "always_create", "do_nothing", "match_existing" ] }, "current_workspace_id": { "type": "integer", "x-nullable": true }, "date_format": { "type": "string", "enum": [ "US", "EU", "ISO" ] }, "default_page": { "type": "string", "enum": [ "last-opened", "calendar", "inbox", "board", "timeline", "reports" ], "x-nullable": true }, "duration_format": { "type": "string", "enum": [ "classic", "improved", "decimal" ] }, "focus_mode_count_up": { "type": "boolean" }, "goal_reminder_time": { "type": "string", "x-nullable": true, "example": "09:00" }, "goal_reminders_enabled": { "type": "boolean" }, "has_reached_task_threshold": { "type": "boolean" }, "import_data_banner_dismissed": { "type": "boolean" }, "language_code": { "type": "string", "x-nullable": true }, "new_users_trial_dismissed": { "type": "boolean" }, "onboarding_calendar_step_at": { "type": "string", "x-nullable": true }, "onboarding_checklist_dismissed": { "type": "boolean" }, "onboarding_completed_at": { "type": "string", "x-nullable": true }, "onboarding_flow_dismissed": { "type": "boolean" }, "onboarding_multi_day_task_created": { "type": "boolean" }, "onboarding_started_at": { "type": "string", "x-nullable": true }, "onboarding_task_dragged": { "type": "boolean" }, "onboarding_tasks_step_at": { "type": "string", "x-nullable": true }, "onboarding_variant_selected": { "type": "string", "x-nullable": true }, "plan_tour_dismissed": { "type": "boolean" }, "platform_nudges": { "type": "object", "additionalProperties": { "type": "string" } }, "pomodoro_mode_auto_start_break": { "type": "boolean" }, "pomodoro_mode_break_duration_mins": { "type": "integer", "minimum": 1 }, "pomodoro_mode_session_duration_mins": { "type": "integer", "minimum": 1 }, "pomodoro_mode_sound_enabled": { "type": "boolean" }, "send_daily_brief": { "type": "boolean" }, "send_timer_notifications": { "type": "boolean" }, "shortcuts_enabled": { "type": "boolean" }, "show_goals_panel": { "type": "boolean" }, "show_google_calendar_events": { "type": "boolean" }, "start_week_on": { "type": "integer", "enum": [ 0, 1 ] }, "switch_to_focus_dismissed": { "type": "boolean" }, "sync_external_calendar": { "type": "string", "enum": [ "never", "always", "ask" ] }, "theme": { "type": "string", "enum": [ "light", "dark", "auto" ] }, "time_block_color": { "type": "string", "x-nullable": true }, "time_format": { "type": "string", "enum": [ "12h", "24h" ] }, "time_tracking_mode": { "type": "string", "enum": [ "focus", "pomodoro" ], "x-nullable": true }, "time_tracking_mode_duration_mins": { "type": "integer", "minimum": 1, "x-nullable": true }, "time_tracking_mode_enabled": { "type": "boolean" }, "time_tracking_mode_fullscreen": { "type": "boolean" }, "tooltip_onboarding_dismissed": { "type": "boolean" }, "tos_ack_decoupled_licenses": { "type": "object", "additionalProperties": { "type": "string" } }, "trial_ended_modal_seen": { "type": "object", "additionalProperties": { "type": "string" } }, "welcome_modal_dismissed": { "type": "boolean" }, "whats_new_may_2026_dismissed": { "type": "boolean" }, "whats_new_tasks_tour_dismissed": { "type": "boolean" } } }, "user.User": { "type": "object", "required": [ "created_at", "deleted_at", "email", "fullname", "id", "updated_at" ], "properties": { "created_at": { "type": "string" }, "deleted_at": { "type": "string" }, "email": { "type": "string", "format": "email" }, "fullname": { "type": "string" }, "id": { "type": "integer" }, "updated_at": { "type": "string" } } }, "usercustomfield.PatchValuesPayload": { "type": "object", "required": [ "custom_fields" ], "properties": { "custom_fields": { "type": "object", "x-nullable": true } } }, "usercustomfield.ValuesResponse": { "type": "object", "required": [ "custom_fields" ], "properties": { "custom_fields": { "type": "object", "additionalProperties": {} } } }, "userworkspace.MergedUserWorkspaceSettings": { "type": "object", "required": [ "approvals_configured", "autolog_time", "is_timesheet_approver" ], "properties": { "active_timesheet_setup_start_date": { "description": "ActiveTimesheetSetupStartDate is the start date of the setup the\ncaller is enrolled in, or null when they are not a member of one.\nIt anchors period computation on the client; the rest of the\nsetup is only needed by the admin management UI, which reads it\nfrom the timesheet-setup list endpoint.", "type": "string", "format": "date", "x-nullable": true }, "approvals_configured": { "type": "boolean" }, "autolog_time": { "type": "boolean" }, "is_timesheet_approver": { "description": "IsTimesheetApprover reports whether the caller is assigned as an\napprover on at least one active setup in this workspace.", "type": "boolean" } } }, "userworkspace.PartialUpdatePayload": { "type": "object", "properties": { "autolog_time": { "type": "boolean", "x-nullable": true } } }, "utilizationtarget.Target": { "type": "object", "required": [ "target_percent", "workspace_id" ], "properties": { "target_percent": { "type": "integer" }, "workspace_id": { "type": "integer" } } }, "utilizationtarget.UpdatePayload": { "type": "object", "required": [ "target_percent" ], "properties": { "target_percent": { "type": "integer", "maximum": 100, "minimum": 1 } } }, "workspace.Currency": { "type": "object", "required": [ "currency", "workspace_id" ], "properties": { "currency": { "type": "string" }, "workspace_id": { "type": "integer" } } }, "workspace.JSONSettings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "boolean" } } }, "workspace.Settings": { "type": "object", "required": [ "created_at", "settings", "updated_at", "workspace_id" ], "properties": { "created_at": { "type": "string" }, "settings": { "$ref": "#/definitions/workspace.JSONSettings" }, "updated_at": { "type": "string" }, "workspace_id": { "type": "integer" } } }, "workspace.UpdateCurrencyPayload": { "type": "object", "required": [ "currency" ], "properties": { "currency": { "type": "string" } } }, "workspace.UpdatePayload": { "type": "object", "required": [ "settings" ], "properties": { "settings": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "boolean" } } } } }, "workspace.UserPermissionsResponse": { "type": "object", "required": [ "permissions" ], "properties": { "permissions": { "type": "array", "items": { "type": "string" } } } } }, "securityDefinitions": { "bearerAuth": { "type": "apiKey", "name": "Authorization", "in": "header" }, "cookieAuth": { "type": "apiKey", "name": "Cookie", "in": "header" }, "queryAuth": { "type": "apiKey", "name": "token", "in": "query" } } }