{ "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}/audit-log/{from}/{to}": { "get": { "security": [ { "cookieAuth": [] } ], "description": "Returns Focus audit-log events across the organization's workspaces within the\ngiven time range, enriched with user, project, client, task, workspace, custom\nfield, custom field option and group summaries. Pass workspace_id to narrow the\nresult to a single workspace.\nRequires a signed Backoffice admin session and the Backoffice view_audit_log\npermission. Customer membership, role, subscription, feature and plan gates do not apply.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Get the audit log of a Focus organization", "operationId": "backoffice-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": "Admin does not have access to audit logs", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Workspace not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Server error", "schema": { "$ref": "#/definitions/response.Error" } }, "503": { "description": "Authorization service unavailable", "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}/daily-brief": { "get": { "security": [ { "cookieAuth": [] } ], "description": "Returns the effective value of the send_daily_brief user setting. A user with no stored settings row, or a row predating the flag, reads as enabled — the same default the send gate applies.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Read whether a Focus user receives Daily Brief emails", "operationId": "backoffice-get-user-daily-brief", "parameters": [ { "type": "integer", "description": "Account-level user ID", "name": "user_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/backoffice.DailyBriefState" } }, "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" } } } }, "patch": { "security": [ { "cookieAuth": [] } ], "description": "Support write path for the send_daily_brief user setting, e.g. to stop the Daily Brief for a user who asked support to. Unlike the product's settings PATCH it does not mark the user's first interaction or emit interaction analytics. The change itself is attributed to the acting admin in the service logs; the comment is the confirmation-modal reason and is not persisted.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Enable or disable Daily Brief emails for a Focus user", "operationId": "backoffice-set-user-daily-brief", "parameters": [ { "type": "integer", "description": "Account-level user ID", "name": "user_id", "in": "path", "required": true }, { "description": "New flag value plus the support reason", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/backoffice.DailyBriefUpdatePayload" } } ], "responses": { "200": { "description": "The value after the write", "schema": { "$ref": "#/definitions/backoffice.DailyBriefState" } }, "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": { "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}/decline": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Records an explicit \"not now\" to the Track or Plan import offer (onboarding step, mobile nudge or web banner) so a declined offer can be told apart from one that was never answered. Append-only, one row per decline.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "importer" ], "summary": "Record that the user declined the offered import.", "operationId": "decline-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": "Decline payload", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/importer.importDeclineRequest" } } ], "responses": { "201": { "description": "The recorded decline", "schema": { "$ref": "#/definitions/importer.ImportDecline" } }, "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": { "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-integration-policies": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the organization's per-integration creation policies. Only integrations an admin has restricted have a row; an integration with no row may create freely, which is the default. Readable by any organization member, because the browser extension must consult it before starting a timer.", "produces": [ "application/json" ], "tags": [ "extension integrations" ], "summary": "List extension integration creation policies", "operationId": "list-extension-integration-policies", "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.ExtensionIntegrationPolicy" } } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/extension-integration-policies/{integration_key}": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates or updates the creation policy for one integration. `integration_key` is the extension source the extension reports: a slug for built-in integrations ('jira-net', 'notion') and the UUID for org-authored custom ones. All three flags are required: the payload states the whole policy, so a partial body can never silently relax a restriction. Requires `manage_extension_integrations`.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "extension integrations" ], "summary": "Set an integration's creation policy", "operationId": "upsert-extension-integration-policy", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "string", "description": "Integration key (extension source)", "name": "integration_key", "in": "path", "required": true }, { "description": "Creation policy payload", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/extensionintegrationpolicy.UpsertPayload" } } ], "responses": { "200": { "description": "Successfully upserted", "schema": { "$ref": "#/definitions/models.ExtensionIntegrationPolicy" } }, "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" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Removes the organization's policy row for one integration, returning it to the default where the extension may create what it cannot match. Idempotent: an integration with no policy is already at the default. Requires `manage_extension_integrations`.", "produces": [ "application/json" ], "tags": [ "extension integrations" ], "summary": "Reset an integration to the default creation policy", "operationId": "delete-extension-integration-policy", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "string", "description": "Integration key (extension source)", "name": "integration_key", "in": "path", "required": true } ], "responses": { "204": { "description": "Successfully reset to the default" }, "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}/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/models.PageWithTotal-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 its id, the user it belongs to, the start and end of the period, and no timestamps. The approval status, policy name, and emoji are included only for a caller who holds the `manage_time_off` permission on the organization; they are omitted for every other caller, and the policy name and emoji are also omitted for an entry that has no category. The endpoint stays 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 fixed hundredths for every currency)", "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 fixed hundredths for every currency)", "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 fixed hundredths for every currency)", "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 fixed hundredths for every currency)", "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'working_minutes' covers the full requested period; 'elapsed_working_minutes' covers only dates through the requester's local today.\nBoth working-minute fields exclude public holidays and deduct overlapping PTO.\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 the requester's 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" }, { "type": "boolean", "description": "break each user's estimated minutes down per task", "name": "include_task_estimates", "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 fixed hundredths for every currency)", "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 fixed hundredths for every currency)", "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 fixed hundredths for every currency)", "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 fixed hundredths for every currency)", "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": "series-shaped listing. A series appears as its template whenever the template matches the listing; instances matching filters their template does not (access, name, completed, ...) appear individually. Supersedes include_idle_recurring_templates while set. Aggregations on a template row describe the template alone (its blueprint tasks, no tracked time), not the series.", "name": "collapse_recurring", "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 completion state (true = completed only, false = non-completed only, empty = all projects, omit = non-completed only while archived resolves false, otherwise all)", "name": "completed", "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/models.PageWithTotal-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}/seed/jobs": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Validates the spec, gates on the acting user being a toggl.com employee, and starts a background seed job for the specified workspace", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "data-generator" ], "summary": "Starts a magic-seed job", "operationId": "start-seed-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 }, { "description": "Seed spec", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/datagenerator.SeedSpec" } } ], "responses": { "202": { "description": "job_id of the started seed job", "schema": { "$ref": "#/definitions/datagenerator.startSeedJobResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Not a toggl.com user", "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" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/seed/jobs/{job_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the progress of a magic-seed job for the specified workspace", "produces": [ "application/json" ], "tags": [ "data-generator" ], "summary": "Gets a magic-seed job", "operationId": "get-seed-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": "Seed job ID", "name": "job_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/datagenerator.SeedJob" } }, "404": { "description": "Seed job not found", "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/users/by-project": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Answers one users-dimension read per requested project lane from a\nsingle shared resolution, replacing N calls to\n/tasks/groups/users?project_id=X. Each lane's groups are identical to\nwhat that single-project read returns for the same parameters.\nEvery lane is answered completely rather than one page at a time, so\na lane with no groups has no members with tasks in range. Groups\ncarry no name, so callers order them after resolving names.", "produces": [ "application/json" ], "tags": [ "task-groups" ], "summary": "Gets users-dimension task groups for several projects at once", "operationId": "get-user-task-groups-by-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": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "project lanes to answer; repeat once per lane, an empty value is the no-project lane. At least 1, at most 25", "name": "project_id", "in": "query", "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 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 to every lane without restricting results to unassigned tasks", "name": "include_unassigned", "in": "query" }, { "type": "boolean", "description": "include projected tasks from unmaterialized recurring periods; requires start_date and end_date", "name": "include_unmaterialized", "in": "query" }, { "type": "boolean", "description": "scope a recurring template's lane to its whole series (template + instances); off keeps every lane scoped to its own project id", "name": "collapse_recurring", "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": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "restrict the user lanes to members whose member (user) custom field values match, combinable with team_id and user_tag_id. Repeatable; each entry is 'fieldID:value1,value2' (values within an entry are OR, separate entries AND). Checkbox fields and the no-value bucket are rejected. Requires the user_custom_fields beta and view_workspace_user_custom_fields.", "name": "user_cf_filter", "in": "query" } ], "responses": { "200": { "description": "Lanes in data, one per requested project in request order, each answered completely", "schema": { "$ref": "#/definitions/taskgroup.projectTaskGroupsResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "user_cf_filter matches too many members; narrow the filter", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/tasks/groups/users/by-team": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Answers one users-dimension read per requested team lane from a\nsingle shared resolution. Each lane carries one group per member of\nthat team with tasks in range; members without tasks are absent, so\nthe caller seeds those from the team roster it already holds. An\nempty team_id value is the no-team lane, which mirrors the flat\nteam_id filter's without-team semantics exactly: it holds tasks\nwhose assignees are on no team and carry no live team assignment,\nso a task shared between a teamless member and a teamed one files\nunder the teamed lane only. A member of two requested teams\nappears in both lanes. Every lane is answered completely rather\nthan one page at a time. Groups carry no name.\nRequesting no lane at all is legal and answers only the unassigned\nbucket — the Teams view starts fully collapsed.", "produces": [ "application/json" ], "tags": [ "task-groups" ], "summary": "Gets users-dimension task groups for several teams at once", "operationId": "get-user-task-groups-by-team", "parameters": [ { "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", "x-nullable": true, "description": "team lanes to answer; repeat once per lane, an empty value is the no-team lane. At most 25", "name": "team_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "x-nullable": true, "description": "scope every lane and the unassigned bucket to these projects (the project timeline); omit on the workspace timeline", "name": "project_id", "in": "query" }, { "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 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", "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": "return the id=0 no-assignee group once in the envelope's unassigned field, without restricting lane results to unassigned tasks; never appended to a lane", "name": "include_unassigned", "in": "query" }, { "type": "boolean", "description": "include projected tasks from unmaterialized recurring periods; requires start_date and end_date", "name": "include_unmaterialized", "in": "query" }, { "type": "boolean", "description": "accepted for parameter parity but ignored on this read: lanes are teams, so there is no project-lane series to collapse", "name": "collapse_recurring", "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": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "restrict the user lanes to members whose member (user) custom field values match, combinable with team_id and user_tag_id. Repeatable; each entry is 'fieldID:value1,value2' (values within an entry are OR, separate entries AND). Checkbox fields and the no-value bucket are rejected. Requires the user_custom_fields beta and view_workspace_user_custom_fields.", "name": "user_cf_filter", "in": "query" } ], "responses": { "200": { "description": "Lanes in data, one per requested team in request order, each answered completely", "schema": { "$ref": "#/definitions/taskgroup.teamTaskGroupsResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "user_cf_filter matches too many members; narrow the filter", "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": "collapse recurring series on the /projects dimension; rrule templates become groups, their instances fold in; other dimensions ignore it", "name": "collapse_recurring", "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": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "restrict the user lanes to members whose member (user) custom field values match, combinable with team_id and user_tag_id. Available for /users only; rejected for other dimensions. Repeatable; each entry is 'fieldID:value1,value2' (values within an entry are OR, separate entries AND). Checkbox fields and the no-value bucket are rejected. Requires the user_custom_fields beta and view_workspace_user_custom_fields.", "name": "user_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" } }, "422": { "description": "user_cf_filter matches too many members; narrow the filter", "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/sync/{client_uuid}": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Upserts a whole time entry. A create is keyed on the client-generated UUID; an update addresses the row by its server `id`. A push wins when its `client_updated_at` is strictly newer than the row's server-stamped `updated_at`; the applied write then advances `updated_at` to the server receipt time, and `client_updated_at` on the response mirrors that value.\n\nLosing is not an error. A push that is older than the stored version, or that targets an entry already deleted, returns 200 with the stored row so the client can converge on it immediately; nothing is written and no events are emitted. Equal timestamps are first-writer-wins and also return the stored row. Every response carries `applied`, which states whether this push is what produced the row — do not try to work it out by comparing the returned row with the one you hold, because the server clamps and re-derives fields on the way in, so a legitimate replay compares as different.\n\nDeletion is absorbing: a push that clears `deleted_at` loses regardless of its timestamp, and the tombstone comes back with 200.\n\n`billable_source` is required and says how to read `billable`. `manual` stores the flag the push sent; `task_default` ignores it and re-derives the flag from the entry's task or project, which is also what keeps the entry in that task's and project's billable cascades.\n\nA push carrying `id` addresses strictly that row: the server never falls back to `client_uuid` and never inserts. If the `id` is unknown, hard-deleted, or belongs to another user, the lookup returns terminal 404 `timeentry_not_found`; do not retry it without `id` to turn it into a create. A push without `id` is a create: the `client_uuid` dedupes it, so re-sending a create returns the existing row rather than inserting a second one.\n\nStart, stop and cancel are ordinary field updates here; there are no dedicated verbs — with one exception. An entry that already carries a duration cannot be made running again by clearing it: that is refused as terminal 400 `cannot_make_entry_running`, exactly as the online PUT refuses it. Start a new entry instead of un-stopping an old one.\nA `client_updated_at` ahead of the server's clock is rejected as `client_timestamp_out_of_window` rather than clamped. This refusal is TRANSIENT: it heals as the clock advances, so back off and re-push the SAME stamp.\n\nTwo bounds are terminal. `client_updated_at` more than 15 days old is refused as `offline_horizon_exceeded`; it is per entry, not per device, and it only bounds a push that is about to be written — a push that has already lost to a newer stored row converges with 200 whatever its age, so a long absence does not turn superseded edits into conflicts. A `start` more than 90 days in the past is refused as `start_too_far_in_past` when the push is actually asserting that start; it is not clamped, because moving an entry to a date the user did not choose and reporting success would leave the device and the server disagreeing forever. `duration` above 24 hours is still clamped.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-entries" ], "summary": "Push a time entry from an offline-capable client", "operationId": "sync-time-entry", "parameters": [ { "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": "client-generated entry UUID", "name": "client_uuid", "in": "path", "required": true }, { "description": "The whole time entry as the client holds it", "name": "timeEntry", "in": "body", "required": true, "schema": { "$ref": "#/definitions/offlinesync.SyncTimeEntryPayload" } } ], "responses": { "200": { "description": "The authoritative stored entry, whether the push won or lost", "schema": { "$ref": "#/definitions/offlinesync.SyncedTimeEntry" } }, "400": { "description": "invalid_params or invalid_body; validation failure; client_timestamp_out_of_window (transient, retry the same stamp); offline_horizon_exceeded; start_too_far_in_past; or cannot_make_entry_running when the addressed entry is already stopped", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "The supplied server id is unknown, hard-deleted, or belongs to another user", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "The time entry falls inside a submitted or approved timesheet period", "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" } }, "503": { "description": "Transient, retry the same push unchanged", "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 it is the setups the caller approves unioned with the setup they are enrolled in as a member. 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.\n\nWith `duration` set (seconds; `start` required alongside it), the call logs a completed entry instead: resolution and creation behave identically, but the entry is created completed and the currently running entry is left untouched. Logging never collides with the running entry, but either mode can return the 409 below when the entry falls in a period locked by an approved timesheet.\n\nOne mode difference worth knowing: the completed-entry path rejects a task that is a template (`invalid_tracking_target`), which the running-start path does not check — the task lookup does not filter templates.\n\nThe `create_*_if_not_found` flags are a request, not a decision: an organization admin can restrict what each integration may create, and this endpoint narrows the request against that policy before acting on it. A restriction can only ever take creation away, and an integration the organization has set no policy for is unrestricted. The effective behaviour is therefore the client's flags AND the organization's, which is why a request asking to create a task can still return a taskless entry.\n\nCreation degrades rather than failing when the caller lacks a permission: a project or tag that cannot be created is omitted, tags that cannot be attached are dropped from the task, and a task that cannot be created at all yields a taskless entry reported as `match_reason: \"taskless_unauthorized\"`.\n\n`task_created`, `project_created`, `tags_created`, `tags_not_found` and `match_reason` describe most of what happened, but not all of it: tags dropped because the caller may not attach them are not reported, so read the returned task's tags to see what it actually carries.\n\nIn a workspace whose required-fields constraint includes `task`, the taskless fallback cannot satisfy that constraint, so a caller who may not create tasks receives a required-fields error rather than a started entry — after any project or tag creations have already persisted.\n\nA `description` is not rejected for exceeding 400 Unicode characters: the started time entry's copy is clipped to the first 400 characters (the same outcome whether the task was matched, created, or the request fell back to taskless), and when this request creates the task the task itself keeps the full description.\n\nDuring the deploy/rollback window while the database still enforces the older, narrower bound, even a description at or below 400 characters may return `description_too_long`.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tracking" ], "summary": "Start tracking, or log a completed entry, 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, or a completed entry logged when duration was set", "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": "Already tracking another entry (start mode only), or the entry falls in a locked period (either mode)", "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. In both modes, a non-empty time-entry user reference that resolves to nobody stops the time entry: the row is skipped in match-only mode and failed otherwise; a blank user cell keeps the importing user as the owner. A project the import creates takes every mapped scalar from its row: description, private, color, status (active/archived/completed), start_date/end_date, estimated_minutes and fixed_fee with its currency (workspace currency when blank); a cell that breaks a rule — an end_date before the start_date or without one, a fee that is unreadable or not greater than zero, a fee with no currency in its row and none on the workspace, an unknown currency, a negative estimated_minutes, a description over 65535 characters, a private or estimate cell the plan or the importing user may not set — is dropped with a warning and the project still imports. A row that names a template (project.template, resolved by exact name among the workspace's unarchived templates the importing user can view) is cloned from it — tasks, fixed fee, rates, alerts, milestones, members and attachments — with the row's mapped cells laid over the template's values (blank inherits) and the template's client scoping the row when it names none; a row that matches an existing project keeps that project, whatever its template cell says, and warns that the template was not applied, and a name that resolves to no template or to several skips a row the import would otherwise create, together with everything scoped to it. A matched project is still updated from its row (custom field values merged, tags linked, members/managers granted, and billable, description, private, color, start_date/end_date, estimated_minutes and fixed_fee set when the cell has a value; a status cell moves it through the app's own archive/unarchive/complete/uncomplete transitions with their cascades — a completed cell is refused on an archived project and on a recurring instance, whose completion would materialize the next one), and so is a matched task (custom field values merged, tags linked, assignees added, and description/notes/estimated_minutes/start_date/end_date/billable/priority/status/recurring set when the cell has a value — archived is create-only, since archiving has to cascade to subtasks and time entries; a status name this workspace doesn't have leaves the task's status alone rather than resetting it, and a recurring value is anchored on its own DTSTART line when it carries one and on the row's start_date otherwise, needing one of the two, and a winning DTSTART also becomes the task's start_date so the series and the task cannot drift apart); 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. A would-create project's scalar cells (dates, fee, currency, private, estimate) are validated the same way the real import validates them, so their warnings show here too, and its template column is resolved — the row matched under the template's client when it names none of its own — so an unknown or ambiguous template name is reported as would-be-skipped. 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, unreadable dates/estimates/fees, an unmatched status name, an invalid priority and a recurring cell that can't be built (including one with neither a DTSTART line of its own nor a start_date on its row) 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}/files/{file_id}/errors": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a CSV in the same shape as the file that was uploaded — same columns, same order — containing only the rows the admin needs to know about, with four diagnostic columns in front: Row (the line number in the uploaded file, header = 1), Result (has_errors, skipped, or imported_with_warnings for a row that landed but not as the file described it), Error Count, and Errors (one line per problem, formatted \"entity · Column — reason\", using the column headers from the uploaded file). The added columns are ignored on re-upload. On a confirmed import the imported_with_warnings rows have already landed: delete them before re-uploading the file as a correction or they import a second time. On a dry-run report nothing has imported yet and the Result names what the import will do.\nServes the dry-run's diagnostics until an import is confirmed and the import's afterwards; the two are never available at the same time. Always offer the download and handle 404 rather than gating on the upload's status — rows dropped while parsing never reach the entity counts, so an import can finish \"completed\" and still have a report.\nKnown limitation on multi-file uploads: a problem with a client, project, task, tag or user is deduplicated across files and carries no file of its own, so it is counted in the report's trailing summary rather than attached to a row that might belong to a different file.", "produces": [ "text/csv" ], "tags": [ "csv-importer" ], "summary": "Download the per-row import errors for one uploaded file", "operationId": "csv-download-file-errors", "parameters": [ { "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": "uploaded file ID", "name": "file_id", "in": "path", "required": true } ], "responses": { "200": { "description": "CSV of the rows that failed, were skipped, or imported with warnings", "schema": { "type": "string" } }, "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 request or file not found, or nothing was recorded for this file", "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, billable flag, scalar columns, fixed fee and lifecycle transitions applied to a matched project (stats.projects.updated counts them), the custom field values, tags, assignees and description/notes/estimated_minutes/start_date/end_date/billable/priority/status/recurring applied to a matched task (stats.tasks.updated counts them) — including any recurring series a matched row started, whose generated instances also survive, 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" } }, "404": { "description": "Shared report or chart not found", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "FX rate missing for the target currency (fx_rate_missing), or the shared report chart cannot be served through a share -- nothing left to render once its member custom fields are removed, or a shape the requested response format cannot render (shared_chart_restricted)", "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" } }, "404": { "description": "Shared report or chart not found", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Currency conversion requested but an FX rate is missing for the period, or the shared report chart cannot be served through a share -- nothing left to render once its member custom fields are removed, or a shape the requested response format cannot render (shared_chart_restricted)", "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.\nTwo body shapes are accepted. The legacy shape is a bare JSON array of filter criteria (dto.FilterRequest), which remains the way to call this endpoint by value.\nThe object shape documented below reads a shared report instead: it requires shared_report_id and chart_key, the stored query's filters replace any filters sent with it, and the dictionary resolves through the share owner's entity access.\nAn object body that names no shared_report_id is rejected as an invalid body.", "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. The generated clients only model this legacy array shape until the FE migrates its shared reads -- the object shape above is accepted on the wire but deliberately not published in the schema yet.", "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" } }, "404": { "description": "Shared report or chart not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/reports/workspaces/{workspace_id}/time-accounting": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns one accounting row per member for the query's period.\nEach row carries logged_minutes, overtime_minutes, holiday_minutes, a leave breakdown, and total_minutes.\nlogged_minutes is tracked time. overtime_minutes is the slice of logged time beyond the member's working minutes; it is a subset of logged time and is not added into total_minutes again.\nleave lists one bucket per time-off policy, each with policy_name, type, and minutes; two policies in the period are two buckets. Leave has no paid/unpaid split.\nholiday_minutes is the member's scheduled minutes on public holidays in the period.\ntotal_minutes is logged_minutes plus all leave plus holiday_minutes.\nperiods holds one team-aggregated row per time bucket over the range, ordered earliest to latest, for the \"hours by period\" chart. Each row has start_date and end_date (clipped to the period) and the same category totals as a member row (logged, leave, holidays, total), summed across every reported member; there is no overtime on a period row.\nperiod_unit is the bucket granularity (day, week, or month), chosen from the range length: up to a week is bucketed per day, up to about two months per week, and a longer range per month. Every bucket in the range is present even when nothing was logged.\nThe request body accepts a period and an optional user_account_id filter; without a filter the report covers every member the caller may read.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "reports" ], "summary": "Generate time accounting report", "operationId": "get-time-accounting-report", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Query configuration with a period and optional user_account_id filter", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/dto.QueryRequest" } } ], "responses": { "200": { "description": "Successfully generated time accounting report", "schema": { "$ref": "#/definitions/timeaccounting.Report" } }, "400": { "description": "Invalid request parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "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" } } } } }, "/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', with a maximum per_page of 200.\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 full-period working, baseline working, elapsed working, scheduled, scheduled draft, and scheduled remaining sums in minutes.\nThe fields are 'sum_working_minutes', 'sum_baseline_working_minutes', 'sum_elapsed_working_minutes', 'sum_scheduled_minutes', 'sum_scheduled_draft_minutes', and 'sum_scheduled_remaining_minutes'.\nWorking minutes exclude public holidays and deduct overlapping PTO. Elapsed working minutes include only dates through the requester's local today.\nBaseline working minutes are the same working minutes before those two deductions (public holidays and overlapping PTO added back), so 'sum_working_minutes' over 'sum_baseline_working_minutes' is the share of capacity that remains. It is never zeroed by the forecasting gate.\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 the requester's local today.\nPast and overdue task slices are zero, while planned events count only from today.\nA breakdown period node shown as time off ('is_time_off' true) also names the dominant policy behind it: 'leave_type' (one of vacation, sick, parental, or other), 'policy_name', and 'emoji'.\nAll three are added only for a caller who holds 'manage_time_off' on the organization, since the leave category is manager-only. When a period spans several policies, the one with the most minutes labels it.\nThese three fields are omitted when the period carries no policy-backed leave, for example a holiday-only period.\nAll three scheduled sums are zeroed unless the caller holds 'view_reports_forecasting', which is mapped to the Premium-only reports_forecasting feature. The response shape is unchanged, so a client without the entitlement degrades to logged-only rather than erroring. 'sum_working_minutes' is never zeroed — capacity is not a forecast.", "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" } }, "404": { "description": "Shared report or chart not found", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Shared report chart cannot be served through a share -- nothing left to render once its member custom fields are removed, or a shape the requested response format cannot render (shared_chart_restricted)", "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 ID, organization ID, and caller role. Session authentication only; API-key callers are rejected.\nRole resolution is best-effort: when it fails the response is still 200 and the role field is omitted. An omitted role means the role is unknown, never that the caller is unrestricted; callers must not use its absence to widen access.", "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}/export-branding": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Resolves, server-side, what an exported PDF report carries for the caller's workspace: the organization logo URL when the feature is enabled, entitled and a logo is uploaded (null otherwise), and whether the \"Made with Toggl\" note renders — on while its flag is on, unless the workspace is entitled to remove it and has it confirmed off. The export request itself carries no branding input.", "produces": [ "application/json" ], "tags": [ "workspace-settings" ], "summary": "Get the branding for exported PDF reports", "operationId": "get-workspace-export-branding", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Branding resolved successfully", "schema": { "$ref": "#/definitions/exportbranding.Branding" } }, "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", "reports.time-off", "reports.time-accounting" ], "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}/saved-views/{id}/schedule": { "put": { "description": "Owner-only. Schedules a saved view, sharing it with the caller first when it has never been shared -- scheduling is a property of a share, so the view needs one to hang the schedule on, and the grant recorded names the caller. Naming any other recipient still requires the report to already reach them, so this cannot share a view with anyone else. Otherwise identical to the shared-report route: complete-state recipients, and a wall-clock time read in each recipient's own timezone.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "ReportSchedules" ], "summary": "Create or replace a saved view's email schedule", "operationId": "upsert-saved-view-schedule", "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": "The complete schedule", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/reportschedule.Payload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.ReportScheduleWithRecipients" } }, "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}/saved-views/{id}/share": { "post": { "description": "Superseded by the grantees form at .../shares, which this is the one-recipient case of. Owner-only, and identical in behaviour: creates or reuses the view's active share, grants the named grantee access, and stores the complete share state on the view. Exactly one of user_id, team_id or workspace_id names the grantee; naming none or more than one is invalid_grantee. Team and workspace grantees additionally require the share_reports_broadly permission. Kept while the clients calling it move across; it will be removed once none are left.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SharedReports" ], "summary": "Share a saved view", "operationId": "share-saved-view", "deprecated": true, "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": "Grantee and the share's complete state", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/sharedreport.SharePayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/sharedreport.BootstrapResponse" } }, "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" } } } } }, "/workspaces/{workspace_id}/saved-views/{id}/shared-report": { "get": { "description": "Owner-only. Returns the saved view's active share and its grants.", "produces": [ "application/json" ], "tags": [ "SharedReports" ], "summary": "Get a saved view's share", "operationId": "get-saved-view-shared-report", "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/sharedreport.BootstrapResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/saved-views/{id}/shares": { "post": { "description": "Owner-only. Creates or reuses the view's active share, grants every named grantee access, and stores the complete share state on the view -- the pinned period and, per chart, the query. One call, one transaction: either every grantee lands or none does. Exactly one of user_id, team_id or workspace_id names each grantee; naming none or more than one is invalid_grantee. A user grantee must be a member of the workspace, a team grantee must be associated with it, and a workspace grantee must be the view's own workspace -- one unreachable grantee refuses the whole call, and the error names it. A grantee already on the share is granted once, not refused, so re-sharing to a list that overlaps the current one is safe. The period is opaque -- stored verbatim; when absent it is stored as absent. Everything else a recipient sees is read live off the view's own params. Team and workspace grantees additionally require the share_reports_broadly permission, so a member may share only with named individuals.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SharedReports" ], "summary": "Share a saved view with several grantees", "operationId": "share-saved-view-many", "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": "Grantees and the share's complete state", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/sharedreport.ShareManyPayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/sharedreport.BootstrapResponse" } }, "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" } } } } }, "/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}/shared-reports/shared-by-me": { "get": { "description": "Lists the live shares of the saved views the authenticated user owns in this workspace. Each entry carries the share id, the view it serves, the period pinned on the share, and every grant standing on it -- including none, for a share whose grantees have all been revoked. A grant naming the caller themselves is omitted: scheduling a view you have not shared records one so the schedule has a share to hang off, and it is machinery rather than an audience. The share bootstrap still returns it.", "produces": [ "application/json" ], "tags": [ "SharedReports" ], "summary": "List shared reports shared by me", "operationId": "list-shared-reports-shared-by-me", "parameters": [ { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/sharedreport.SharedByMeEntry" } } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/shared-reports/shared-with-me": { "get": { "description": "Lists the shared reports a live grant admits the authenticated user to in this workspace. Discovery only -- each entry carries the share id, the view's display metadata, and the owner.", "produces": [ "application/json" ], "tags": [ "SharedReports" ], "summary": "List shared reports shared with me", "operationId": "list-shared-reports-shared-with-me", "parameters": [ { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "$ref": "#/definitions/sharedreport.SharedWithMeEntry" } } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/shared-reports/{id}": { "get": { "description": "Returns the projection a grantee opens a shared report with -- the owner, the view's display metadata, the owner's own params reduced to an allow-list of the keys the owner's save writes (flexqFilters, period, rounding, currency, zeroTimeRows, viewInMyTimezone, presentation), the share's pinned period, and the keys of the stored charts. Member (user) custom fields are removed from the params entirely -- from the filters and from the display state naming each chart's groupings -- and from the report's own query, so what the recipient is seeded with describes the report they get. The stored queries are never included. Every refusal -- no grant, revoked, deleted share or view, departed owner or caller -- is the same undifferentiated 404.", "produces": [ "application/json" ], "tags": [ "SharedReports" ], "summary": "Get a shared report for viewing", "operationId": "get-shared-report-for-viewer", "parameters": [ { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Shared report ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/sharedreport.ViewerResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/shared-reports/{id}/grants": { "post": { "description": "Owner-only. Grants every named grantee access to a share that already exists and leaves the share's stored state untouched -- the pinned period and the per-chart queries stay exactly as the last share call published them. That is the difference from sharing a saved view, which republishes that state as part of the same call: a caller adding a recipient from their inventory of shares is not looking at the view and has no state to send. One call, one transaction: either every grantee lands or none does. Exactly one of user_id, team_id or workspace_id names each grantee; naming none or more than one is invalid_grantee. A user grantee must be a member of the workspace, a team grantee must be associated with it, and a workspace grantee must be the share's own workspace -- one unreachable grantee refuses the whole call, and the error names it. A grantee already on the share is granted once, not refused. Team and workspace grantees additionally require the share_reports_broadly permission, so a member may add only named individuals. A share that does not exist, was deleted, or belongs to somebody else is the same undifferentiated not-found.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SharedReports" ], "summary": "Add grantees to a shared report", "operationId": "add-shared-report-grants", "parameters": [ { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Shared report ID", "name": "id", "in": "path", "required": true }, { "description": "The grantees to add", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/sharedreport.GrantsPayload" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/sharedreport.BootstrapResponse" } }, "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" } } } } }, "/workspaces/{workspace_id}/shared-reports/{id}/grants/{grant_id}": { "delete": { "description": "Owner-only. Revokes one grantee's access to a shared report.", "tags": [ "SharedReports" ], "summary": "Revoke a shared report grant", "operationId": "revoke-shared-report-grant", "parameters": [ { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Shared report ID", "name": "id", "in": "path", "required": true }, { "type": "integer", "description": "Grant ID", "name": "grant_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" } } } } }, "/workspaces/{workspace_id}/shared-reports/{id}/schedule": { "put": { "description": "Owner-only. Complete-state: the recipients sent become exactly the schedule's recipients, and they must all be people the report is shared with. The time is a wall clock read in each recipient's own timezone, so one schedule sends at as many instants as its recipients have timezones.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "ReportSchedules" ], "summary": "Create or replace a shared report's email schedule", "operationId": "upsert-shared-report-schedule", "parameters": [ { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Shared report ID", "name": "id", "in": "path", "required": true }, { "description": "The complete schedule", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/reportschedule.Payload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.ReportScheduleWithRecipients" } }, "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" } } } }, "delete": { "description": "Owner-only. Soft-deletes the schedule; the shared report and its grants are untouched, and the report can be scheduled again afterwards.", "produces": [ "application/json" ], "tags": [ "ReportSchedules" ], "summary": "Stop a shared report's email schedule", "operationId": "delete-shared-report-schedule", "parameters": [ { "type": "integer", "description": "Workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "Shared report ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "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}/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. With include_usage, each tag carries usage counts of the projects, tasks and time entries directly tagged with it; usage is omitted for callers whose project access is restricted.", "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" }, { "type": "boolean", "description": "hydrate per-tag usage counts (settings surface only; adds a warehouse read)", "name": "include_usage", "in": "query" }, { "type": "boolean", "description": "list archived tags alongside active ones; an explicit archived param still wins", "name": "include_archived", "in": "query" }, { "type": "boolean", "description": "filter by archived state (true = archived only, false = active only, omit = active only, empty = all tags). Omitting it alongside tag_id returns those ids whatever their state, so an archived tag still attached to an entity resolves.", "name": "archived", "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. A name already held in the workspace is skipped and the rest are still created, so the response can be shorter than the request; a name repeated inside the batch is rejected with tag_name_duplicate, and a batch whose names all already exist with tag_names_all_taken.", "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/archive": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Archives several tags by the provided IDs. All-or-nothing: if any ID is unknown, outside the workspace, or deleted, nothing is archived. Already-archived tags are no-ops.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Bulk archive tags", "operationId": "bulk-archive-tags", "parameters": [ { "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/tag.BulkArchivePayload" } } ], "responses": { "204": { "description": "Successfully archived 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 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/bulk/unarchive": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Unarchives several tags by the provided IDs. All-or-nothing: if any ID is unknown, outside the workspace, or deleted, nothing is unarchived. Already-active tags are no-ops.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Bulk unarchive tags", "operationId": "bulk-unarchive-tags", "parameters": [ { "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/tag.BulkUnarchivePayload" } } ], "responses": { "204": { "description": "Successfully unarchived 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 deleted", "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}/archive": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Archives a tag. The tag disappears from the apply affordance but stays attached to and readable on every existing entity — nothing cascades. Archiving an already-archived tag is a no-op.", "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Archive a tag", "operationId": "archive-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 archived tag" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Tag does not exist or is deleted", "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}/tags/{tag_id}/unarchive": { "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Unarchives a tag, returning it to the apply affordance. Unarchiving an active tag is a no-op.", "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Unarchive a tag", "operationId": "unarchive-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 unarchived tag" }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Tag does not exist or is deleted", "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" } } } } }, "/workspaces/{workspace_id}/watermark": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns whether the workspace's exported PDF reports carry the \"Made with Toggl\" mark. Defaults to true when none has been set.", "produces": [ "application/json" ], "tags": [ "workspace-settings" ], "summary": "Get workspace watermark visibility", "operationId": "get-workspace-watermark", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Watermark visibility retrieved successfully", "schema": { "$ref": "#/definitions/workspace.Watermark" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Sets whether the workspace's exported PDF reports carry the \"Made with Toggl\" mark.\nHiding the mark requires the plan-linked remove_report_watermark permission; restoring it requires the workspace role but not the linked plan feature.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "workspace-settings" ], "summary": "Set workspace watermark visibility", "operationId": "update-workspace-watermark", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Watermark payload", "name": "watermark", "in": "body", "required": true, "schema": { "$ref": "#/definitions/workspace.UpdateWatermarkPayload" } } ], "responses": { "200": { "description": "Watermark visibility updated successfully", "schema": { "$ref": "#/definitions/workspace.Watermark" } }, "400": { "description": "Invalid request body", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Hiding the watermark is not available on the current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "User is not authorized to update the workspace watermark", "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.DailyBriefState": { "type": "object", "required": [ "send_daily_brief" ], "properties": { "send_daily_brief": { "type": "boolean" } } }, "backoffice.DailyBriefUpdatePayload": { "type": "object", "required": [ "send_daily_brief" ], "properties": { "comment": { "type": "string", "maxLength": 2000 }, "send_daily_brief": { "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", "minimum": 0 }, "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" }, "rollup_enabled": { "type": "boolean" }, "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. In both modes,\na non-empty time-entry user reference that resolves to nobody stops the\ntime entry: the row is skipped in match-only mode and failed otherwise. A\nblank user cell keeps the importing user as the owner. Time entries whose\ntask and user are matched are still imported 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, description,\nprivate, color, start_date, end_date, estimated_minutes and fixed_fee with\nits currency are each written when the row carries a value, left alone when\nthe cell is blank or the column unmapped. A status cell moves the project\nthrough the app's own archive, unarchive, complete and uncomplete\ntransitions and their cascades; completing is refused on an archived\nproject, and on a recurring instance whose completion would materialize the\nnext one. Two cells the write can still refuse under its row lock, dropping\nthe cell with a warning and keeping the rest of the row: a visibility that\nwould leave the project disagreeing with its parent, and a date pair that\nno longer fits what the project stores by then. The project's client\nbinding is never changed, and the template column is ignored in this mode.\nLinking a tag that doesn't exist yet creates that tag; nothing else is\ncreated. These updates are NOT reverted by the revert endpoint, which only\nremoves rows the import created.\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, notes, estimated_minutes, start_date, end_date, billable,\npriority, status and recurring are each written when the row carries a\nvalue and left alone when the cell is blank or the column unmapped. The\ntask's project, client and parent bindings are never changed. archived is\nthe one mapped task column this mode does not apply: archiving a task has\nto cascade to its subtasks and time entries, which an import cannot do at\nCSV scale, so the column is read only when a task is created. Like the\nproject updates, none of this is reverted.\n\nstatus resolves against this workspace's own statuses, matched\ncase-insensitively, ignoring spaces and dashes. A name this workspace\ndoesn't have puts a new task on the workspace default status but leaves a\nmatched task's status alone — unlike every other column here, a miss does\nnot fall back to overwriting what the task already had.\n\nrecurring is anchored on its own DTSTART line when it names one, and on\nthe row's start_date otherwise; with neither the value is ignored with a\nwarning, same in both modes. A winning DTSTART also becomes the task's\nstart_date, warning when the row named a different day — the domain keeps\na parent series' start_date and DTSTART as one value, so importing them\napart would have the first edit of the task reshape the series. A matched\ntask that already belongs to a recurring series is one of the two matches\nthis mode refuses outright (see below) — recurring here can only start a\nnew series on a task that doesn't have one, never edit an existing one. A\ntemplate or rolled-up task can't carry a recurrence either; the value is\ndropped for that row rather than failing it. The series' instances are\ngenerated once tags and assignees have been linked, a step or two after\nthe row that set the recurrence completes.\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_active_status, member_rate_segments,\nmember_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_active_status, member_rate_segments,\nmember_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_active_status": { "description": "MemberActiveStatus counts activations and deactivations in the\nORGANIZATION. Its own slot rather than folded into MemberRoles: a role\nchange decides what somebody can do in this workspace, this decides\nwhether they are a member at all, and they are gated by different\npermissions — so one count covering both would be a number no admin could\nact on.", "allOf": [ { "$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, scalar, fixed-fee or\ncustom-field values were applied or whose status cell moved it through one\nof the app's lifecycle transitions, a match-existing-only task whose\nscalars or custom-field values were applied, an adopted project/task/client\n(the integration linkage is stamped), a re-imported row whose custom-field\nmerge altered the blob, a matched custom field that gained select options,\nor a rate row whose timeline was rewritten. Disjoint from Matched — a row\nis 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.UnsettableFieldDetail": { "type": "object", "required": [ "features", "field", "permission", "reason" ], "properties": { "features": { "description": "Features carries the subscription features the plan is missing, and is\nempty for every reason other than \"plan\". Never null.", "type": "array", "items": { "$ref": "#/definitions/csv.UnsettableFieldFeature" } }, "field": { "description": "Field is the qualified target (\"project.private\"), as in unsettable_fields.", "type": "string" }, "permission": { "description": "Permission is the authorization label checked for this field.", "type": "string" }, "reason": { "description": "Reason is one of the UnsettableReason* constants.", "type": "string" } } }, "csv.UnsettableFieldFeature": { "type": "object", "required": [ "feature_id", "friendly_name", "upsell_plan_handle", "upsell_plan_id" ], "properties": { "feature_id": { "type": "integer" }, "friendly_name": { "type": "string" }, "upsell_plan_handle": { "type": "string", "x-nullable": true }, "upsell_plan_id": { "type": "integer", "x-nullable": true } } }, "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" }, "x-nullable": true }, "unsettable_fields_detail": { "description": "UnsettableFieldsDetail mirrors the field on UploadResponse, with the same\nnil-means-not-computed rule as UnsettableFields above.", "type": "array", "items": { "$ref": "#/definitions/csv.UnsettableFieldDetail" }, "x-nullable": true }, "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", "unsettable_fields_detail", "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" } }, "unsettable_fields_detail": { "description": "UnsettableFieldsDetail names the same targets as UnsettableFields and adds\nwhy each is refused: a plan that lacks the feature (with the feature and\nthe plan that unlocks it, so the screen can upsell) or a role that lacks\nthe permission (where no plan helps and the admin's admin does).\n\nParallel to UnsettableFields rather than replacing it: that field is the\ncontract clients already read, and it keeps its exact shape.", "type": "array", "items": { "$ref": "#/definitions/csv.UnsettableFieldDetail" } }, "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.ApprovalsSpec": { "type": "object", "required": [ "approvers", "enabled", "members_in_cycle_ratio" ], "properties": { "approved_ratio": { "description": "ApprovedRatio is the share of those submitted timesheets an approver\nthen approves, oldest first, leaving the rest awaiting review.", "type": "number" }, "approvers": { "type": "integer" }, "enabled": { "type": "boolean" }, "members_in_cycle_ratio": { "type": "number" }, "submitted_ratio": { "description": "SubmittedRatio is the share of each enrolled member's complete past\nperiods that get submitted, oldest first. Without it the setup exists\nbut every timesheet sits at not_submitted and the approvals list is\nempty.", "type": "number" } } }, "datagenerator.MembersSpec": { "type": "object", "required": [ "activate", "count" ], "properties": { "activate": { "type": "boolean" }, "count": { "type": "integer" }, "include_self": { "description": "IncludeSelf adds the acting user to the tracking and approvals pool\nalongside the created dummy members, so the person running the seed\nalso gets data in the workspace. It's meaningful only when Members is\npresent: a members-absent spec already attributes everything to the\nacting user. The FE surfaces this as a checkbox that defaults on.", "type": "boolean" }, "password": { "description": "Password is required only when Activate is true (see validate); a\ndeactivated dummy member never needs one.", "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" } } }, "datagenerator.ProjectsSpec": { "type": "object", "required": [ "count", "private_ratio", "with_tasks_ratio" ], "properties": { "archived_ratio": { "description": "ArchivedRatio is the share of projects archived at the very end of the\nrun, after they have been tracked against, so the workspace ends up\nwith archived projects that have real history behind them.", "type": "number" }, "auto_compute_estimates": { "description": "AutoComputeEstimates sets a project's estimate to the sum of its task\nestimates, which is what makes project progress (tracked over estimate)\nagree with the per-task estimates the tasks stage derives from capacity.\n\nOff by default, and deliberately opt-in: the project service gates any\nproject carrying an estimate behind PermissionManageProjectEstimates,\nwhich is itself feature-gated — so on a workspace whose plan does not\ninclude it, a spec with this set fails the projects stage outright, even\nfor a workspace admin. Everything else the seed writes works without it;\nonly project progress reads empty.", "type": "boolean" }, "billable_ratio": { "description": "BillableRatio is the share of projects created billable. Entries\ninherit billability from their task's project (timeentry's\ntask_default billable source), so this is the one knob that moves\nUtilization, which is billable time over capacity. A nil ratio means\nevery project is billable, which is what the engine did before the\nfield existed.", "type": "number" }, "count": { "type": "integer" }, "custom_fields": { "description": "CustomFields creates a small set of project custom fields and fills\nthem in on every seeded project. Requires the project_custom_fields\nbeta on the workspace; without it the stage fails with the custom\nfield service's own error rather than silently skipping.", "type": "boolean" }, "private_ratio": { "type": "number" }, "with_tasks_ratio": { "type": "number" } } }, "datagenerator.RatesSpec": { "type": "object", "required": [ "billable_max", "billable_min", "currency", "labor_max", "labor_min" ], "properties": { "billable_max": { "type": "integer" }, "billable_min": { "description": "BillableMin and BillableMax bound the per-member billable rate, in\ncents per hour. Max must be \u003e= Min.", "type": "integer" }, "currency": { "description": "Currency is the ISO 4217 code both rates are written in.", "type": "string" }, "labor_max": { "type": "integer" }, "labor_min": { "description": "LaborMin and LaborMax bound the per-member labor cost, same units.", "type": "integer" } } }, "datagenerator.ScheduleSpec": { "type": "object", "required": [ "hours_per_day" ], "properties": { "hours_per_day": { "description": "HoursPerDay is the working day every pool member gets on the weekdays\ntheir pattern covers. Must be in (0,24].", "type": "number" }, "part_time_ratio": { "description": "PartTimeRatio is the share of the pool put on a four-day week\n(Monday–Thursday) instead of Monday–Friday.", "type": "number" } } }, "datagenerator.SeedJob": { "type": "object", "required": [ "counts", "created_at", "error", "job_id", "organization_id", "stage", "status", "updated_at", "user_id", "workspace_id" ], "properties": { "counts": { "type": "object" }, "created_at": { "type": "string" }, "error": { "type": "string" }, "job_id": { "type": "string" }, "organization_id": { "type": "integer" }, "stage": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string" }, "user_id": { "type": "integer" }, "workspace_id": { "type": "integer" } } }, "datagenerator.SeedSpec": { "type": "object", "properties": { "approvals": { "$ref": "#/definitions/datagenerator.ApprovalsSpec" }, "clients": { "type": "integer" }, "members": { "$ref": "#/definitions/datagenerator.MembersSpec" }, "projects": { "$ref": "#/definitions/datagenerator.ProjectsSpec" }, "rates": { "$ref": "#/definitions/datagenerator.RatesSpec" }, "schedule": { "$ref": "#/definitions/datagenerator.ScheduleSpec" }, "tags": { "$ref": "#/definitions/datagenerator.TagsSpec" }, "tasks": { "$ref": "#/definitions/datagenerator.TasksSpec" }, "tracking": { "$ref": "#/definitions/datagenerator.TrackingSpec" }, "usage_mix": { "$ref": "#/definitions/datagenerator.UsageMix" } } }, "datagenerator.TagsSpec": { "type": "object", "required": [ "attach_ratio", "count" ], "properties": { "attach_ratio": { "description": "AttachRatio is the share of each taggable entity that receives a tag.", "type": "number" }, "count": { "type": "integer" } } }, "datagenerator.TasksSpec": { "type": "object", "required": [ "count" ], "properties": { "count": { "type": "integer" } } }, "datagenerator.TrackingSpec": { "type": "object", "required": [ "end_date", "start_date", "taskless_ratio" ], "properties": { "end_date": { "type": "string" }, "start_date": { "type": "string" }, "taskless_ratio": { "type": "number" } } }, "datagenerator.UsageMix": { "type": "object", "required": [ "heavy", "light", "normal" ], "properties": { "heavy": { "type": "integer" }, "light": { "type": "integer" }, "normal": { "type": "integer" } } }, "datagenerator.startSeedJobResponse": { "type": "object", "required": [ "job_id" ], "properties": { "job_id": { "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" }, "weekly_working_hours_is_default": { "type": "boolean" } } }, "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", "view_in_my_timezone" ], "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" } }, "chart_key": { "description": "ChartKey selects which of the shared report's stored chart queries to run. Required\nwhenever SharedReportID is present, and meaningless without it.", "type": "string" }, "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" }, "shared_report_id": { "description": "SharedReportID names a shared report to read instead of running this request.\nIts presence changes what the whole body means: the report runs the owner's stored\nquery as the owner, and every other field here — fragments, period, pagination — is\ndiscarded. Absent, the request is served by value exactly as it always was.", "type": "integer" }, "transformations": { "type": "array", "items": { "$ref": "#/definitions/dto.TransformationRequest" } }, "view_in_my_timezone": { "description": "ViewInMyTimezone converts every local time in the report into the requesting\nuser's own timezone instead of the one each entry was tracked in. The timezone\nitself is never taken from the payload: the API resolves it from the requester's\naccount preference. Restricted to requesters who read other members' time.", "type": "boolean" } } }, "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" ] }, "exportbranding.Branding": { "type": "object", "required": [ "logo_url", "show_watermark" ], "properties": { "logo_url": { "description": "The organization's logo URL, or null when the header stays\nToggl-only: flag off, plan not entitled, or no logo uploaded.", "type": "string", "x-nullable": true }, "show_watermark": { "description": "Whether the document carries the \"Made with Toggl\" note: its beta\nflag is on and the workspace has not — entitled and confirmed —\nswitched the mark off.", "type": "boolean" } } }, "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" } } }, "extensionintegrationpolicy.UpsertPayload": { "type": "object", "required": [ "create_project_if_not_found", "create_tags_if_not_found", "create_task_if_not_found" ], "properties": { "create_project_if_not_found": { "type": "boolean" }, "create_tags_if_not_found": { "type": "boolean" }, "create_task_if_not_found": { "type": "boolean" } } }, "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" }, "duration": { "description": "Duration switches the call from starting a running entry to logging\na completed one: resolution and creation behave identically, but the\nentry is created with this duration (seconds, matching\ntime_entry.duration everywhere else; `start` is required alongside\nit — a completed entry without a start would be invisible to every\nrange query) and the currently running entry is left untouched.", "type": "integer", "minimum": 0 }, "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.ImportDecline": { "type": "object", "required": [ "created_at", "id", "source_product_id", "surface", "user_id", "workspace_id" ], "properties": { "created_at": { "type": "string" }, "id": { "type": "integer" }, "source_product_id": { "type": "integer" }, "source_workspace_id": { "type": "integer" }, "surface": { "type": "string" }, "user_id": { "type": "integer" }, "workspace_id": { "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.importDeclineRequest": { "type": "object", "required": [ "source_product_id", "surface" ], "properties": { "source_product_id": { "type": "integer", "example": 1 }, "source_workspace_id": { "type": "integer", "example": 623123 }, "surface": { "type": "string", "enum": [ "onboarding", "nudge", "banner" ], "example": "onboarding" } } }, "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" }, "role": { "type": "string" }, "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", "elapsed_working_minutes", "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" }, "elapsed_working_minutes": { "description": "Working minutes through the requester's local today.", "type": "integer" }, "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 the requester's 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" }, "task_estimates": { "description": "TaskEstimates breaks the computations' estimated minutes down per task,\nonly populated when include_task_estimates is requested.", "type": "array", "items": { "$ref": "#/definitions/models.TaskDailyEstimate" } }, "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" }, "rollup_enabled": { "description": "RollupEnabled marks a parent whose totals come from its subtasks, so\nclients must not offer to reassign it. Non-required so existing generated\nclient literals still typecheck.", "type": "boolean" }, "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.ExtensionIntegrationPolicy": { "type": "object", "required": [ "create_project_if_not_found", "create_tags_if_not_found", "create_task_if_not_found", "created_at", "integration_key", "organization_id", "updated_at" ], "properties": { "create_project_if_not_found": { "type": "boolean" }, "create_tags_if_not_found": { "type": "boolean" }, "create_task_if_not_found": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "integration_key": { "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.GrantPermission": { "type": "string", "enum": [ "view", "edit", "full" ], "x-enum-varnames": [ "GrantPermissionView", "GrantPermissionEdit", "GrantPermissionFull" ] }, "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_EffectiveProjectRatesSummary": { "type": "object", "required": [ "data", "page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.EffectiveProjectRatesSummary" } }, "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-orgprivate_Group": { "type": "object", "required": [ "data", "page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/orgprivate.Group" } }, "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" }, "recurring_project_id": { "description": "RecurringProjectID links an instance to its recurring template, so\nclients can lane an entry under a collapsed series.", "type": "integer" } } }, "models.ProjectTaskGroups": { "type": "object", "required": [ "groups", "project_id" ], "properties": { "groups": { "description": "The user groups for this lane, identical to what the single-project\nusers-dimension read returns for the same parameters.", "type": "array", "items": { "$ref": "#/definitions/models.TaskGroup" } }, "project_id": { "description": "The project the lane was requested for. Null is the no-project lane.", "type": "integer", "x-nullable": true } } }, "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.ReportScheduleWithRecipients": { "type": "object", "required": [ "cadence", "created_at", "created_by", "id", "recipient_team_ids", "recipient_user_ids", "recipient_workspace_ids", "send_time", "shared_report_id" ], "properties": { "cadence": { "enum": [ "daily", "weekly", "monthly" ], "allOf": [ { "$ref": "#/definitions/models.ScheduleCadence" } ] }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "integer" }, "deleted_at": { "type": "string", "format": "date-time" }, "id": { "type": "integer" }, "recipient_team_ids": { "type": "array", "items": { "type": "integer" } }, "recipient_user_ids": { "type": "array", "items": { "type": "integer" } }, "recipient_workspace_ids": { "type": "array", "items": { "type": "integer" } }, "send_day": { "description": "SendDay is nil for daily, a weekday (0=Sunday) for weekly, and a\nday-of-month (1-28) for monthly.", "type": "integer" }, "send_time": { "type": "string" }, "shared_report_id": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } }, "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", "reports.time-off", "reports.time-accounting" ] }, "updated_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "integer" } } }, "models.ScheduleCadence": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "x-enum-varnames": [ "ScheduleCadenceDaily", "ScheduleCadenceWeekly", "ScheduleCadenceMonthly" ] }, "models.SharedReport": { "type": "object", "required": [ "created_at", "created_by", "id", "saved_view_id" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "integer" }, "deleted_at": { "type": "string", "format": "date-time" }, "id": { "type": "integer" }, "saved_view_id": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } }, "models.SharedReportGrant": { "type": "object", "required": [ "created_at", "created_by", "id", "permission", "shared_report_id" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "integer" }, "deleted_at": { "type": "string", "format": "date-time" }, "grantee_team_id": { "type": "integer" }, "grantee_user_id": { "type": "integer" }, "grantee_workspace_id": { "type": "integer" }, "id": { "type": "integer" }, "permission": { "enum": [ "view", "edit", "full" ], "allOf": [ { "$ref": "#/definitions/models.GrantPermission" } ] }, "shared_report_id": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } }, "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": { "archived_at": { "description": "An archived tag disappears from the apply affordance but stays attached\nto and readable on every existing entity. Nothing cascades.", "type": "string", "format": "date-time" }, "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" }, "usage": { "description": "Counts of the projects, tasks and time entries whose tag set directly\ncontains this tag. Only present on the tags list, for callers with\nunrestricted project access.", "allOf": [ { "$ref": "#/definitions/models.TagUsage" } ], "x-nullable": true }, "workspace_id": { "type": "integer" } } }, "models.TagLite": { "type": "object", "required": [ "id", "name" ], "properties": { "color": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" } } }, "models.TagUsage": { "type": "object", "required": [ "projects", "tasks", "time_entries" ], "properties": { "projects": { "type": "integer" }, "tasks": { "type": "integer" }, "time_entries": { "type": "integer" } } }, "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" }, "rollup_enabled": { "type": "boolean" }, "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.TaskDailyEstimate": { "type": "object", "required": [ "daily_estimated_minutes", "task_id" ], "properties": { "daily_estimated_minutes": { "description": "DailyEstimatedMinutes is the assignee's per-working-day share, after\nallocations, the assignee split, and their own working days and public\nholidays. Unrounded, because Computation.EstimatedMinutes rounds once\nafter summing every task's share: round each part first and the parts\nstop adding up to the total. Clients round for display.", "type": "number" }, "task_id": { "type": "integer" } } }, "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.TeamTaskGroups": { "type": "object", "required": [ "groups", "team_id" ], "properties": { "groups": { "description": "The user groups for this lane: one per member of the team with tasks in\nrange. Members without tasks are absent — the consumer seeds those from\nthe team roster it already holds.", "type": "array", "items": { "$ref": "#/definitions/models.TaskGroup" } }, "team_id": { "description": "The team the lane was requested for. Null is the no-team lane.", "type": "integer", "x-nullable": true } } }, "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 creator's IANA timezone snapshotted at creation;\nNULL 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 entry creator's IANA timezone snapshotted at creation;\nNULL 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" } } }, "offlinesync.SyncTimeEntryPayload": { "type": "object", "required": [ "billable_source", "client_updated_at", "type" ], "properties": { "billable": { "type": "boolean" }, "billable_source": { "description": "BillableSource says whether Billable above is the user's own decision or\na value inherited from the task or project, and it is required because\nneither default is recoverable: a payload carrying only `billable: true`\ncannot distinguish a manual true from an inherited one, and a manual value\nmay legitimately equal the current default -- which may itself have changed\nwhile the device was offline. Defaulting either way silently rewrites the\nentry's relationship to its task.", "enum": [ "manual", "task_default" ], "allOf": [ { "$ref": "#/definitions/models.BillableSource" } ] }, "calendar_event_id": { "description": "CalendarEventID is honoured on a create and ignored on an update: the\ncalendar link is server-owned once the row exists, and re-pointing it is\nnot something a device may do. An update carrying a different value still\nreports applied, because the rest of the push did land -- this is the one\nfield where the stored row will not match what was sent.", "type": "integer", "x-nullable": true }, "client_updated_at": { "description": "ClientUpdatedAt is the device's own edit clock, bumped on every local\nedit. It is the only ordering input in the protocol, and required,\nbecause a push without one cannot be ordered against anything.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "DeletedAt makes a delete an ordinary field update ordered by the same\nclock. Deletion is absorbing, so a later push that clears it loses\nregardless of its timestamp.", "type": "string", "format": "date-time", "x-nullable": true }, "description": { "type": "string", "x-nullable": true }, "duration": { "type": "integer", "minimum": 0, "x-nullable": true }, "id": { "description": "ID is the authoritative server identity for an update. When present the\nserver resolves only this row, never falling back to the URL uuid.", "type": "integer", "x-nullable": true }, "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 }, "start": { "type": "string", "format": "date-time", "x-nullable": true }, "tag_ids": { "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": { "enum": [ "activity", "break" ], "allOf": [ { "$ref": "#/definitions/models.TimeEntryType" } ] } } }, "offlinesync.SyncedTimeEntry": { "type": "object", "required": [ "applied", "client_updated_at", "client_uuid", "created_at", "id", "toggl_user_id", "type", "workspace_id" ], "properties": { "applied": { "description": "Applied reports whether this push is what produced the row. It is stated\nrather than left to be inferred: the server clamps and re-derives fields\non the way in, so comparing the returned row against the one held is the\nsame whole-entity comparison the protocol rejects as not well-defined.", "type": "boolean" }, "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" }, "client_updated_at": { "description": "ClientUpdatedAt mirrors the stored server-stamped updated_at -- the\nordering value the device converges on. It is not a win/lose signal on\nits own: an applied write advances it to the server receipt time, so it\ndiffers from the sent stamp whether the push won or lost. Read Applied.", "type": "string", "format": "date-time", "x-nullable": true }, "client_uuid": { "description": "ClientUUID is the device-minted identity bound to this entry, or null\nwhen it has none.", "type": "string", "format": "uuid", "x-nullable": true }, "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 entry creator's IANA timezone snapshotted at creation;\nNULL 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" } } }, "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", "accounts_role_id", "active", "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" }, "accounts_role_id": { "type": "integer" }, "active": { "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" } } } }, "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": { "description": "HourlyRate uses fixed hundredths of the currency's major unit for every\ncurrency (e.g. 5000 = USD 50.00 or JPY 50).", "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": { "description": "HourlyRate uses fixed hundredths of the currency's major unit for every\ncurrency (e.g. 5000 = USD 50.00 or JPY 50).", "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": { "description": "HourlyRate uses fixed hundredths of the currency's major unit for every\ncurrency (e.g. 5000 = USD 50.00 or JPY 50).", "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" } } }, "reportschedule.Payload": { "type": "object", "required": [ "cadence", "time" ], "properties": { "cadence": { "enum": [ "daily", "weekly", "monthly" ], "allOf": [ { "$ref": "#/definitions/models.ScheduleCadence" } ] }, "day": { "description": "Day is required for weekly (a weekday, 0=Sunday) and monthly (1-28),\nand refused for daily.", "type": "integer" }, "recipient_team_ids": { "type": "array", "items": { "type": "integer" } }, "recipient_user_ids": { "description": "At least one recipient overall, of any kind. A team or workspace is\nresolved to its members when the report is sent, not now.", "type": "array", "items": { "type": "integer" } }, "recipient_workspace_ids": { "type": "array", "items": { "type": "integer" } }, "time": { "description": "Time is a wall clock, hours and minutes, read in each recipient's\nown timezone.", "type": "string" } } }, "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", "reports.time-off", "reports.time-accounting" ] } } }, "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", "reports.time-off", "reports.time-accounting" ] } } }, "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", "matched_terms", "name" ], "properties": { "client_name": { "type": "string" }, "color": { "type": "string" }, "id": { "type": "integer" }, "matched_terms": { "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", "matched_terms", "name" ], "properties": { "client_name": { "type": "string" }, "id": { "type": "integer" }, "matched_terms": { "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", "matched_terms" ], "properties": { "client_name": { "type": "string" }, "description": { "type": "string" }, "last_tracked_at": { "type": "string", "format": "date-time" }, "matched_terms": { "type": "integer" }, "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": { "emoji": { "description": "Emoji is the emoji of the entry's time-off policy (category). Included only for a caller who holds the\nmanage_time_off permission; omitted for everyone else and for an entry with no category.", "type": "string" }, "end_time": { "description": "EndTime is the RFC3339 timestamp (UTC) the time off period ends at; always after StartTime.", "type": "string" }, "policy_name": { "description": "PolicyName is the name of the entry's time-off policy (category). Included only for a caller who holds the\nmanage_time_off permission; omitted for everyone else and for an entry with no category.", "type": "string" }, "start_time": { "description": "StartTime is the RFC3339 timestamp (UTC) the time off period starts at.", "type": "string" }, "status": { "description": "Status is the approval state of the entry: pending, approved, rejected or canceled. Included only for a caller who holds the\nmanage_time_off permission; omitted for everyone else.", "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 } } }, "sharedreport.BootstrapResponse": { "type": "object", "required": [ "grants", "shared_report" ], "properties": { "grants": { "type": "array", "items": { "$ref": "#/definitions/models.SharedReportGrant" } }, "schedule": { "description": "Schedule is null when the share is not scheduled, which is an\nordinary state rather than an absent field.", "allOf": [ { "$ref": "#/definitions/models.ReportScheduleWithRecipients" } ] }, "shared_report": { "$ref": "#/definitions/models.SharedReport" } } }, "sharedreport.ChartPayload": { "type": "object", "required": [ "flexq_query" ], "properties": { "flexq_query": { "type": "object" } } }, "sharedreport.GranteePayload": { "type": "object", "properties": { "team_id": { "type": "integer" }, "user_id": { "type": "integer" }, "workspace_id": { "type": "integer" } } }, "sharedreport.GrantsPayload": { "type": "object", "required": [ "grantees" ], "properties": { "grantees": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "$ref": "#/definitions/sharedreport.GranteePayload" } } } }, "sharedreport.OwnedViewSummary": { "type": "object", "required": [ "name", "saved_view_id", "type" ], "properties": { "icon_name": { "type": "string" }, "name": { "type": "string" }, "saved_view_id": { "type": "integer" }, "type": { "type": "string" } } }, "sharedreport.ShareManyPayload": { "type": "object", "required": [ "charts", "grantees" ], "properties": { "charts": { "type": "object", "additionalProperties": { "$ref": "#/definitions/sharedreport.ChartPayload" } }, "grantees": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "$ref": "#/definitions/sharedreport.GranteePayload" } }, "period": { "type": "object" } } }, "sharedreport.SharePayload": { "type": "object", "required": [ "charts" ], "properties": { "charts": { "type": "object", "additionalProperties": { "$ref": "#/definitions/sharedreport.ChartPayload" } }, "period": { "type": "object" }, "team_id": { "type": "integer" }, "user_id": { "type": "integer" }, "workspace_id": { "type": "integer" } } }, "sharedreport.SharedByMeEntry": { "type": "object", "required": [ "grants", "shared_report_id", "view" ], "properties": { "grants": { "type": "array", "items": { "$ref": "#/definitions/models.SharedReportGrant" } }, "period": { "type": "object" }, "shared_report_id": { "type": "integer" }, "view": { "$ref": "#/definitions/sharedreport.OwnedViewSummary" } } }, "sharedreport.SharedViewSummary": { "type": "object", "required": [ "name", "type" ], "properties": { "icon_name": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "sharedreport.SharedWithMeEntry": { "type": "object", "required": [ "owner_user_id", "shared_report_id", "view" ], "properties": { "owner_user_id": { "type": "integer" }, "shared_report_id": { "type": "integer" }, "view": { "$ref": "#/definitions/sharedreport.SharedViewSummary" } } }, "sharedreport.ViewerResponse": { "type": "object", "required": [ "chart_keys", "owner_user_id", "presentation", "view" ], "properties": { "chart_keys": { "type": "array", "items": { "type": "string" } }, "owner_user_id": { "type": "integer" }, "period": { "type": "object" }, "presentation": { "type": "object" }, "view": { "$ref": "#/definitions/sharedreport.SharedViewSummary" } } }, "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.BulkArchivePayload": { "type": "object", "required": [ "tag_ids" ], "properties": { "tag_ids": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "type": "integer" } } } }, "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.BulkUnarchivePayload": { "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" }, "private": { "description": "Optional privacy override applied to every duplicated task (and cascaded\nchildren). When omitted, each task keeps the source task's private flag.\nUsed when FE must force public (plan lacks private tasks) or private\n(user can only create private) instead of falling back to composite create.", "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", "minimum": 0 }, "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" }, "rollup_enabled": { "type": "boolean" }, "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", "minimum": 0 }, "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" }, "rollup_enabled": { "type": "boolean" }, "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", "minimum": 0, "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 }, "rollup_enabled": { "type": "boolean" }, "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", "minimum": 0, "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 }, "rollup_enabled": { "type": "boolean" }, "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" }, "rollup_enabled": { "type": "boolean" }, "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", "minimum": 0 }, "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" }, "rollup_enabled": { "type": "boolean" }, "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.projectTaskGroupsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.ProjectTaskGroups" } } } }, "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" } } }, "taskgroup.teamTaskGroupsResponse": { "type": "object", "required": [ "data", "unassigned" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.TeamTaskGroups" } }, "unassigned": { "description": "The view-level no-assignee bucket, resolved once for the whole request\nrather than repeated per lane. Null when nothing is unassigned or when\ninclude_unassigned was not requested.", "allOf": [ { "$ref": "#/definitions/models.TaskGroup" } ], "x-nullable": true } } }, "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 } } }, "timeaccounting.LeaveBucket": { "type": "object", "required": [ "minutes", "policy_name", "type" ], "properties": { "minutes": { "type": "integer" }, "policy_name": { "type": "string" }, "type": { "type": "string" } } }, "timeaccounting.MemberReport": { "type": "object", "required": [ "holiday_minutes", "leave", "logged_minutes", "overtime_minutes", "total_minutes", "user_account_id" ], "properties": { "holiday_minutes": { "type": "integer" }, "leave": { "type": "array", "items": { "$ref": "#/definitions/timeaccounting.LeaveBucket" } }, "logged_minutes": { "type": "integer" }, "overtime_minutes": { "type": "integer" }, "total_minutes": { "type": "integer" }, "user_account_id": { "type": "integer" } } }, "timeaccounting.PeriodReport": { "type": "object", "required": [ "end_date", "holiday_minutes", "leave", "logged_minutes", "start_date", "total_minutes" ], "properties": { "end_date": { "type": "string" }, "holiday_minutes": { "type": "integer" }, "leave": { "type": "array", "items": { "$ref": "#/definitions/timeaccounting.LeaveBucket" } }, "logged_minutes": { "type": "integer" }, "start_date": { "type": "string" }, "total_minutes": { "type": "integer" } } }, "timeaccounting.Report": { "type": "object", "required": [ "members", "period_unit", "periods" ], "properties": { "members": { "description": "Members holds one accounting row per member, ordered by user_account_id.", "type": "array", "items": { "$ref": "#/definitions/timeaccounting.MemberReport" } }, "period_unit": { "description": "PeriodUnit is the bucket granularity of Periods (day, week, or month),\nchosen from the range length. It disambiguates a clipped edge bucket whose\nday span would otherwise not reveal the granularity.", "type": "string" }, "periods": { "description": "Periods holds one team-aggregated row per time bucket over the period,\nordered from earliest to latest, for the \"hours by period\" chart. When at\nleast one member is reported, every bucket in the range is present even with\nnothing logged, so the chart draws a bar per bucket; with no members it is\nempty.", "type": "array", "items": { "$ref": "#/definitions/timeaccounting.PeriodReport" } } } }, "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 creator's IANA timezone snapshotted at creation;\nNULL 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 creator's IANA timezone snapshotted at creation;\nNULL 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 entry creator's IANA timezone snapshotted at creation;\nNULL 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" }, "emoji": { "description": "Emoji is the emoji of the entry's time-off policy (category). Populated only on the Get and\nGetByEntities reads; omitted on Post/Put and the batch responses even for a categorized entry.", "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" }, "policy_name": { "description": "PolicyName is the name of the entry's time-off policy (category). Populated only on the\nGet and GetByEntities reads, which join the category; omitted on Post/Put and the batch responses.", "type": "string" }, "start_time": { "description": "StartTime is the RFC3339 timestamp (UTC) the time off period starts at.", "type": "string" }, "status": { "description": "Status is the approval state of the entry: pending, approved, rejected or canceled.\nThe server column is NOT NULL, so Get, GetByEntities, Post, Put and the batch responses all carry it.", "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.UpdateWatermarkPayload": { "type": "object", "required": [ "show_watermark" ], "properties": { "show_watermark": { "type": "boolean" } } }, "workspace.UserPermissionsResponse": { "type": "object", "required": [ "permissions" ], "properties": { "permissions": { "type": "array", "items": { "type": "string" } } } }, "workspace.Watermark": { "type": "object", "required": [ "show_watermark", "workspace_id" ], "properties": { "show_watermark": { "type": "boolean" }, "workspace_id": { "type": "integer" } } } }, "securityDefinitions": { "bearerAuth": { "type": "apiKey", "name": "Authorization", "in": "header" }, "cookieAuth": { "type": "apiKey", "name": "Cookie", "in": "header" } } }