{ "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": "integer", "description": "Project ID; matches the project's own events and those of its tasks, time logs, planned time and custom field values", "name": "project_id", "in": "query" }, { "type": "integer", "description": "Custom field ID; matches the field's own definition and option events plus every value set, changed or cleared on it", "name": "custom_field_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" } } } }, "post": { "security": [ { "cookieAuth": [] } ], "description": "Starts a full-workspace Track import as the organization owner through the Focus importer, so\nevery product check applies to the owner: source availability, the manage_imports permission,\nand one active import per workspace. No session is stored with the import: each Track step\nmints a short-lived owner session and revokes it when the step ends. An active import that has\nreported progress within the importer's stale threshold is rejected with 409\nimport_already_in_progress before any audit event is written; the job is returned in\nerror_values.job. A stale active import is passed to the importer, which may keep it, and then\nit is returned with already_running set. Requires a signed Backoffice admin session and the\nBackoffice manage_workspaces permission; the reason is stored in a Backoffice audit event written\nbefore the import starts.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Start a Track import into a Focus workspace", "operationId": "backoffice-start-workspace-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 parameters", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/backoffice.startWorkspaceImportPayload" } } ], "responses": { "202": { "description": "Import started", "schema": { "$ref": "#/definitions/backoffice.StartWorkspaceImportResponse" } }, "400": { "description": "Invalid request or source workspace not available", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Admin lacks manage_workspaces", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Workspace not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "An import is already in progress (import_already_in_progress)", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Organization owner not found (owner_not_found) or not allowed to import into the workspace (owner_forbidden)", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } }, "502": { "description": "No session could be created for the organization owner (owner_session_failed)", "schema": { "$ref": "#/definitions/response.Error" } }, "503": { "description": "Authorization service unavailable, import starts not configured (import_start_not_configured), or Track imports disabled (track_importer_disabled)", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/backoffice/organizations/{organization_id}/workspaces/{workspace_id}/import-jobs/current": { "get": { "security": [ { "cookieAuth": [] } ], "description": "BackOffice-authenticated read using the importer's active-job visibility rules.\nUnconfirmed legacy dispatches are hidden. Reading never settles a stuck job; stale is true when the\njob has no recent persisted progress. Stale does not establish workflow failure.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Get the active Focus workspace import job", "operationId": "backoffice-get-current-workspace-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": "The active import job", "schema": { "$ref": "#/definitions/backoffice.CurrentImportJobResponse" } }, "204": { "description": "No active import job" }, "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/{job_id}": { "get": { "security": [ { "cookieAuth": [] } ], "description": "BackOffice-authenticated detail of one Track/Plan import job: the list fields, the persisted\nnon-secret start parameters, and every workflow attempt with its diagnostics.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "backoffice" ], "summary": "Get a Focus workspace import job", "operationId": "backoffice-get-workspace-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/backoffice.ImportJobDetailView" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Workspace or import job 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/{job_id}/log": { "get": { "security": [ { "cookieAuth": [] } ], "description": "BackOffice-authenticated CSV download of the entity/linking log of one Track/Plan import job.\nThe log contains member emails, so it requires the Backoffice manage_workspaces permission.", "produces": [ "text/csv" ], "tags": [ "backoffice" ], "summary": "Download a Focus workspace import job log", "operationId": "backoffice-download-workspace-import-job-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" } }, "403": { "description": "Admin lacks manage_workspaces", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Workspace, import job, or import log not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } }, "503": { "description": "Authorization service unavailable, or import logs not configured (import_log_not_configured)", "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" } } } } }, "/email/unsubscribe/{token}": { "get": { "description": "A GET on the List-Unsubscribe URL has no side effect (link scanners follow GETs); it redirects to the web app's confirmation page with the token, and the email kind when it can be read, so the page can pre-select its copy. The token is not verified here.", "tags": [ "user-settings" ], "summary": "Redirect a browser to the unsubscribe confirmation page", "operationId": "email-unsubscribe-page", "parameters": [ { "type": "string", "description": "Signed unsubscribe token from the email", "name": "token", "in": "path", "required": true } ], "responses": { "302": { "description": "Redirect to {PublicURL}/unsubscribe" } } }, "post": { "description": "Turns off the one email the token was issued for (its kind), without a session. Accepts the RFC 8058 one-click body from mail providers (form-encoded, exactly `List-Unsubscribe=One-Click`) or an empty JSON body from the confirmation page. Idempotent, and synchronous, so a 200 means the flag is already off. Never answers 401.", "consumes": [ "application/json", "application/x-www-form-urlencoded" ], "produces": [ "application/json" ], "tags": [ "user-settings" ], "summary": "Unsubscribe from one Focus email via a signed link", "operationId": "email-unsubscribe", "parameters": [ { "type": "string", "description": "Signed unsubscribe token from the email", "name": "token", "in": "path", "required": true } ], "responses": { "200": { "description": "The email is turned off", "schema": { "$ref": "#/definitions/emailunsubscribe.Response" } }, "400": { "description": "Unrecognized body or a malformed / tampered token", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Unsubscribe links are disabled in this deployment", "schema": { "$ref": "#/definitions/response.Error" } }, "410": { "description": "The token has expired", "schema": { "$ref": "#/definitions/response.Error" } }, "429": { "description": "Too many requests for this token or address", "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 running import job of a workspace or, when none runs, the job whose imported data is being deleted (its data_deletion.status is deleting).", "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. An identical repeated request from the same user while that import is active returns the existing job instead of starting another.", "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, or the existing active job for an identical repeated request", "schema": { "$ref": "#/definitions/importer.ImportJob" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Not authorized to import into this workspace, or the source product's importer is disabled (plan_importer_disabled, track_importer_disabled)", "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}/delete-data": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Starts an asynchronous deletion of the time entries, tasks, projects, clients and tags the import run created in this workspace. Parents still referenced by other live data are kept. A repeated request while the deletion runs returns the job unchanged; a failed deletion can be requested again. The summary fills in while the deletion runs: deleted counts the rows removed across every attempt, skipped counts the rows the latest attempt kept.", "produces": [ "application/json" ], "tags": [ "importer" ], "summary": "Delete the data an import run brought in", "operationId": "delete-import-data", "parameters": [ { "type": "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": { "202": { "description": "The import job with its data deletion state", "schema": { "$ref": "#/definitions/importer.ImportJobResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Not authorized to delete this import's data", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Import job not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "An import is still running, Track sync is not disabled, or the data was already deleted", "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}/jobs/{job_id}/retry": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Starts a new fenced attempt for an import job that is in a retryable failed state. Requires an Idempotency-Key header; the same key returns the same attempt. Bounded to a fixed number of attempts.", "produces": [ "application/json" ], "tags": [ "importer" ], "summary": "Retry a failed import job", "operationId": "retry-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": "string", "description": "import job ID", "name": "job_id", "in": "path", "required": true }, { "type": "string", "description": "idempotency key", "name": "Idempotency-Key", "in": "header", "required": true } ], "responses": { "200": { "description": "The retried import job", "schema": { "$ref": "#/definitions/importer.ImportJob" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Not authorized to retry this import, or the source product's importer is disabled (plan_importer_disabled, track_importer_disabled)", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Import job not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Import is not retryable, is already active, or reached the attempt limit", "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, or the source product's importer is disabled (plan_importer_disabled, track_importer_disabled)", "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": "integer", "description": "Project ID; matches the project's own events and those of its tasks, time logs, planned time and custom field values", "name": "project_id", "in": "query" }, { "type": "integer", "description": "Custom field ID; matches the field's own definition and option events plus every value set, changed or cleared on it", "name": "custom_field_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 policy rows. Each row carries two independent sets of flags: `create_*_if_not_found`, which govern what a start may CREATE, and `use_*`, which govern what the extension may SUPPLY at all — a start may be forbidden to attach a project it resolved even where creating one is allowed. The reserved key `__default__` holds the organization-wide rule; any other key overrides it for that one integration. A client resolving an integration's policy must apply specific-over-default precedence: its own row if present, else the `__default__` row, else unrestricted. 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 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. The three create flags are required. The `use_*` flags are optional and an omitted one keeps whatever already governs the integration: its stored value when the row exists, otherwise the organization's `__default__` rule, falling back to permissive only when there is no default either. So a client that predates them cannot relax a restriction by saving the rest, nor by creating a fresh row that would outrank a restrictive default. 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": "Clears a policy row's creation settings. Removing an integration's own row returns it to the organization-wide `__default__` rule, which may itself be restrictive — it does not necessarily re-allow creation. Removing the reserved `__default__` key clears the organization-wide creation rule, leaving every integration without its own row unrestricted for creation. Idempotent: removing a row that does not exist succeeds. Requires `manage_extension_integrations`.\n\nThe reserved `__default__` row is NOT deleted while it carries any `use_*` restriction: its creation flags are reset to permissive and the restrictions are kept. The shipped extension resets creation by calling this endpoint, and a client that predates `use_*` must not be able to lift the organization-wide restriction it cannot represent — the same guarantee the upsert makes by preserving omitted fields. An integration's own row is always deleted outright, which returns that integration to the `__default__` rule rather than to no rule. A caller that genuinely wants no organization-wide policy at all sets every flag explicitly via the upsert.", "produces": [ "application/json" ], "tags": [ "extension integrations" ], "summary": "Remove one creation policy row", "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": "Policy row removed" }, "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. `definition` is always the complete document; `overlay` is the delta against a shipped integration, when the row customises one. A create either stores both or neither; there is no prior row for it to clear, since a duplicate id is a 409 rather than an update.", "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. `definition` is always the complete document; `overlay` is the delta against a shipped integration, when the row customises one. The two are representations of one document, so send both or neither — **a save that omits `overlay` clears it**, demoting the row to a standalone definition rather than leaving a stale delta a newer client would prefer.", "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/orgprivate.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 organization's current active Focus plan trial. Add-on module trials (Capacity, Time Off) are excluded: they run alongside the organization's own plan rather than standing in for it.", "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/balances": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns each visible member's balance as of `date`, today when omitted, in each active policy that has balance changes. A member sees their own, a team lead also their teams', and a caller with the organization-wide `view_time_off` permission everyone's. Requires `view_time_off_balance` or `manage_time_off_balance`.", "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "List members' time off balances", "operationId": "list-timeoff-balances", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Only these users, at most 500", "name": "user_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Only these policies", "name": "category_id", "in": "query" }, { "type": "string", "description": "As-of date (YYYY-MM-DD)", "name": "date", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/orgprivate.TimeOffUserBalance" } } }, "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" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Records a manual change to a member's balance in a policy. The user must be an active member and the policy the organization's. Requires `manage_time_off_balance`. Responds 201 with the recorded change.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Adjust a member's time off balance", "operationId": "create-timeoff-balance-adjustment", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "description": "Balance change", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/orgprivate.TimeOffBalanceAdjustmentInput" } } ], "responses": { "201": { "description": "Successful operation", "schema": { "$ref": "#/definitions/orgprivate.TimeOffBalanceChange" } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden, or the user is not an active member", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Policy not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/timeoff/balances/bulk": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Sets each member's starting balance in one policy for the current year, in one transaction; resending the same rows changes nothing. The policy must be limited, yearly or one-off, with a yearly allowance above 0. At most 10,000 rows and 2 MiB. Rows of members not eligible for a balance are skipped and reported. Any invalid row fails the request with 422 and the row failures, and nothing is written. Requires `manage_time_off_balance`.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Set members' starting balances", "operationId": "import-timeoff-balances", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "description": "Starting balances", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/orgprivate.TimeOffBalanceImportInput" } } ], "responses": { "200": { "description": "Written, including any skipped rows", "schema": { "$ref": "#/definitions/orgprivate.TimeOffBalanceImportResult" } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Policy not found", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Invalid rows; nothing written", "schema": { "$ref": "#/definitions/orgprivate.TimeOffBalanceImportResult" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/timeoff/categories": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the organization's time off policies, archived ones included. Entries reference a policy by `time_off_category_id`. Requires the `view_time_off_categories` organization permission.", "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "List time off policies", "operationId": "list-timeoff-categories", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/orgprivate.TimeOffCategory" } } }, "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" } } } }, "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates a time off policy. A limited policy with an allowance credits every member assigned the Time Off module at once: this year's allowance, prorated when `prorate` is true, or this month's share on a monthly policy. Requires `create_time_off_categories`. Responds 201 with the policy.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Create a time off policy", "operationId": "create-timeoff-category", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "description": "Policy", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/orgprivate.TimeOffCategoryCreateInput" } } ], "responses": { "201": { "description": "Successful operation", "schema": { "$ref": "#/definitions/orgprivate.TimeOffCategory" } }, "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/categories/{category_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns one time off policy. Requires the `view_time_off_categories` organization permission.", "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Get a time off policy", "operationId": "get-timeoff-category", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Policy ID", "name": "category_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/orgprivate.TimeOffCategory" } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Policy not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Replaces a policy's settings. Send every field: an omitted one is cleared or zeroed. The policy as read is the template, except that `prorate` is sent as true or false; true sets the proration date to the request time, also when proration is already on. `accrual_frequency` and `allowance_type` cannot change. Requires `update_time_off_categories`.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Update a time off policy", "operationId": "update-timeoff-category", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Policy ID", "name": "category_id", "in": "path", "required": true }, { "description": "Policy settings", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/orgprivate.TimeOffCategoryUpdateInput" } } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/orgprivate.TimeOffCategory" } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Policy not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Deletes a policy no entry uses. Answers 409 with `time_off_category_in_use` when one does or `time_off_category_system_default` for the default policy. Requires `delete_time_off_categories`.", "tags": [ "time-off" ], "summary": "Delete a time off policy", "operationId": "delete-timeoff-category", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Policy ID", "name": "category_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Policy not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Policy in use or default policy", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/timeoff/categories/{category_id}/archive": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Archives a policy. Requires `update_time_off_categories`.", "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Archive a time off policy", "operationId": "archive-timeoff-category", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Policy ID", "name": "category_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/orgprivate.TimeOffCategory" } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Policy not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/timeoff/categories/{category_id}/restore": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Restores an archived policy. Requires `update_time_off_categories`.", "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Restore a time off policy", "operationId": "restore-timeoff-category", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Policy ID", "name": "category_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/orgprivate.TimeOffCategory" } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Policy not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/timeoff/entries": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a page of time off entries, latest start first, in any status unless filtered. A member sees their own entries, a team lead also their teams', and a caller with the organization-wide `view_time_off` permission everyone's; filters only narrow that set. `from` and `to` select entries overlapping the days between them, both included. `id` is the value the per-user entry endpoints call `timeoff_id`; dates carry no offset and are UTC.", "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "List time off entries", "operationId": "list-timeoff-entries", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Only these users", "name": "user_id", "in": "query" }, { "type": "integer", "description": "Only this team; the caller must lead it or view the whole organization", "name": "team_id", "in": "query" }, { "type": "integer", "description": "Only this policy", "name": "category_id", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "Only these statuses: pending, approved, rejected, canceled", "name": "status", "in": "query" }, { "type": "string", "description": "Window start (YYYY-MM-DD)", "name": "from", "in": "query" }, { "type": "string", "description": "Window end (YYYY-MM-DD)", "name": "to", "in": "query" }, { "type": "integer", "description": "Page number, from 1", "name": "page", "in": "query" }, { "type": "integer", "description": "Page size, 1 to 500 (default 50)", "name": "rows", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/orgprivate.TimeOffEntriesPage" } }, "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/entries/{entry_id}": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns one time off entry in any status, with the names and emails of its requester, approver and creator. Open to the entry's owner, a team lead of the owner, and a caller with the organization-wide `view_time_off` permission.", "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Get a time off entry", "operationId": "get-timeoff-entry", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Entry ID", "name": "entry_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/orgprivate.TimeOffEntryWithUsers" } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Entry not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/timeoff/entries/{entry_id}/approve": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Approves a pending entry, charges its days to the requester's balance in its policy, and notifies the requester as the web app does. Requires the organization-wide `approve_time_off` permission or leading a team of the requester. Answers 409 when the entry is not pending.", "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Approve a time off entry", "operationId": "approve-timeoff-entry", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Entry ID", "name": "entry_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/orgprivate.TimeOffEntry" } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Entry not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Entry not pending", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/timeoff/entries/{entry_id}/cancel": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Cancels a pending or approved entry and returns any days it charged. Notifies the requester unless they cancel it themselves. Open to the entry's owner, a team lead of the owner, and a caller with the organization-wide `cancel_time_off` permission. Answers 409 when the entry is already rejected or canceled.", "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Cancel a time off entry", "operationId": "cancel-timeoff-entry", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Entry ID", "name": "entry_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/orgprivate.TimeOffEntry" } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Entry not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Entry already rejected or canceled", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/timeoff/entries/{entry_id}/reject": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Rejects a pending entry and notifies the requester, with the reason when given, as the web app does. The body is optional. Access as for approving. Answers 409 when the entry is not pending.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Reject a time off entry", "operationId": "reject-timeoff-entry", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "Entry ID", "name": "entry_id", "in": "path", "required": true }, { "description": "Rejection reason", "name": "payload", "in": "body", "schema": { "$ref": "#/definitions/orgprivate.TimeOffRejectInput" } } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/orgprivate.TimeOffEntry" } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Entry not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Entry not pending", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/timeoff/reports/absence": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns leave and balances per member and policy over a period of at most 732 days: balance figures as of `end_date`, and leave inside the period split at today. Covers everyone for a caller with the organization-wide `view_time_off` permission, the led teams for a team lead, otherwise the caller alone. Requires `view_time_off_balance` or `manage_time_off_balance`.", "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Get the absence report", "operationId": "get-timeoff-absence-report", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "string", "description": "Period start (YYYY-MM-DD)", "name": "start_date", "in": "query", "required": true }, { "type": "string", "description": "Period end (YYYY-MM-DD)", "name": "end_date", "in": "query", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Only these users", "name": "user_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Only these teams, at most 50", "name": "team_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Only these policies", "name": "category_id", "in": "query" }, { "type": "boolean", "description": "Count pending leave as scheduled", "name": "include_pending", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/orgprivate.TimeOffAbsenceReport" } }, "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/timeline": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the time off entries overlapping the days from `from` to `to`, both included, ordered by start: pending and approved unless `status` says otherwise. Visibility and filters as in the entries list; no pagination.", "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "List the time off timeline", "operationId": "list-timeoff-timeline", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Only these users", "name": "user_id", "in": "query" }, { "type": "integer", "description": "Only this team; the caller must lead it or view the whole organization", "name": "team_id", "in": "query" }, { "type": "integer", "description": "Only this policy", "name": "category_id", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "Only these statuses: pending, approved, rejected, canceled", "name": "status", "in": "query" }, { "type": "string", "description": "Window start (YYYY-MM-DD)", "name": "from", "in": "query" }, { "type": "string", "description": "Window end (YYYY-MM-DD)", "name": "to", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/orgprivate.TimeOffTimelineEntry" } } }, "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`, `time_off_category_id` and `daily_breakdown`. Omitting `type` clears it. Omitting `time_off_category_id` or `daily_breakdown` keeps the stored value; a kept breakdown must still fall within the new dates, or the request fails with a 400. 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 a policy (`time_off_category_id`), a `daily_breakdown` and a legacy `type`. The sum of `daily_breakdown` is the entry's day count, charged to the user's balance in its policy and counted in the absence report; an entry without a breakdown counts 0 days. 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}/timeoff/users/{user_id}/balances": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the user's balance as of `date`, today when omitted, in each active policy that has balance changes; unlimited policies usually have none and are then absent. Requires `view_time_off_balance` or `manage_time_off_balance`. A member reads only their own balances, a team lead their team's, and a caller with organization-wide `view_time_off` anyone's.", "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "Get a user's time off balances", "operationId": "get-timeoff-balances-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": "integer", "description": "Only this policy", "name": "category_id", "in": "query" }, { "type": "string", "description": "As-of date (YYYY-MM-DD)", "name": "date", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/orgprivate.TimeOffBalance" } } }, "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}/balances/changes": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a page of the user's balance changes in one policy that are already in effect, newest first. Access follows the balances endpoint.", "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "List a user's time off balance changes", "operationId": "list-timeoff-balance-changes-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": "integer", "description": "Policy ID", "name": "category_id", "in": "query", "required": true }, { "type": "integer", "description": "Only this accrual year", "name": "year", "in": "query" }, { "type": "integer", "description": "Page number, from 1", "name": "page", "in": "query" }, { "type": "integer", "description": "Page size, 1 to 500 (default 50)", "name": "rows", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/orgprivate.TimeOffBalanceChangesPage" } }, "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/whos-out": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns every active member's pending and approved time off overlapping `start_date` to `end_date`, both included, at most 7 days. Open to any member of the organization.", "produces": [ "application/json" ], "tags": [ "time-off" ], "summary": "List who's out", "operationId": "list-timeoff-whos-out", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "string", "description": "Window start (YYYY-MM-DD)", "name": "start_date", "in": "query", "required": true }, { "type": "string", "description": "Window end (YYYY-MM-DD)", "name": "end_date", "in": "query", "required": true } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "$ref": "#/definitions/orgprivate.TimeOffWhosOutEntry" } } }, "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": "boolean", "description": "Only users with a Track role and no Focus role in the workspace, excluding the owner and organization admins (the set POST track-team-invites acts on); requires workspaces to name exactly one workspace", "name": "track_without_focus", "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" }, { "type": "boolean", "description": "Include whether each member has a calendar integration connected. Requires the workspaces param to name exactly one workspace and the view_external_calendar_integrations permission on it", "name": "include_calendar_integration", "in": "query" }, { "type": "boolean", "description": "Include each member's workspace designations; requires workspaces to name exactly one workspace and the view_workspace_designations permission on it", "name": "include_designations", "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; designations is present only when include_designations=true, the caller holds view_workspace_designations, and the lookup succeeded; has_calendar_integration is present only when include_calendar_integration=true, the caller holds view_external_calendar_integrations, and the calendar lookup succeeded", "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": { "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Replaces the working hours of every listed user with the given schedule: either a single row without a weekday (a weekly total) or up to 56 weekday rows of at most 24 hours each, where several rows may share a weekday (time blocks). All or nothing: every user's schedule is replaced in one transaction, and any failure returns an error status with nothing changed for anyone. Each user's existing rows are replaced by new ones. A weekday row may set `starting_hours`; a row without it keeps the user's existing start time for that weekday when it is the only row for that weekday. Re-sending the same request is safe and produces the same schedule with new row ids. Requires the `manage_working_hours` organization permission. Responds 400, and changes nothing, for an empty or duplicated `user_ids` list, more than 100 users, or an invalid schedule. Responds 200 with each user's resulting schedule, in request order.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "Working Hours" ], "summary": "Set the same working hours for many organization users", "operationId": "replace-working-hours-for-users", "parameters": [ { "type": "integer", "description": "Organization ID", "name": "organization_id", "in": "path", "required": true }, { "description": "Users and the schedule to set", "name": "working_hours", "in": "body", "required": true, "schema": { "$ref": "#/definitions/shareddata.BulkWorkingHoursInput" } } ], "responses": { "200": { "description": "Each user's resulting working hours", "schema": { "$ref": "#/definitions/shareddata.BulkWorkingHoursResponse" } }, "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}/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": "integer", "description": "Project ID; matches the project's own events and those of its tasks, time logs, planned time and custom field values", "name": "project_id", "in": "query" }, { "type": "integer", "description": "Custom field ID; matches the field's own definition and option events plus every value set, changed or cleared on it", "name": "custom_field_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}/calendar/events": { "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). Replaces the deprecated `GET .../tasks/calendar`.", "produces": [ "application/json" ], "tags": [ "calendar" ], "summary": "Get raw calendar events", "operationId": "calendar-events-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 }, { "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" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/calendar/sync": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Materializes the user's external calendar events over the given range. `degraded_integrations` holds calendar **integration** ids (not calendar ids) that could not be refreshed because an error is recorded against them — usually a revoked OAuth grant, though an unmapped provider error records one too. The sync still succeeded for every calendar it could reach; these need the user to reconnect the integration. Replaces the deprecated `PUT .../tasks/calendar`.\nPass `skip_provider_refresh=true` to skip the live calendar provider refresh before syncing.", "produces": [ "application/json" ], "tags": [ "calendar" ], "summary": "Sync external calendar events for a date range", "operationId": "calendar-sync-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 }, { "type": "boolean", "description": "skip the live calendar provider refresh before syncing (default false: refresh happens)", "name": "skip_provider_refresh", "in": "query" } ], "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}/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.\nWithout 'view_extended_capacity_horizon' the requested period is limited to the requester's current week or month, from the earlier week or month start through the later week or month end.\nA requested period entirely outside that window returns no computations.", "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; required when team_id is absent", "name": "user_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "resolve team members and compute capacity for them; required when user_id is absent", "name": "team_id", "in": "query" }, { "type": "string", "description": "start date of computation (inclusive)", "name": "start_date", "in": "query", "required": true }, { "type": "string", "description": "end date of computation (inclusive)", "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" } }, "402": { "description": "Feature not available on the current plan", "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" } }, "402": { "description": "The plan does not cover the requested milestones", "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 and time entries in bulk.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "composite" ], "summary": "Creates the main task, subtasks 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" } }, "402": { "description": "Not available on the current plan", "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" } }, "422": { "description": "Values still hold more than one member", "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}/allowed-users": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the member ids a users custom field can be set to. An empty list means every workspace member.", "produces": [ "application/json" ], "tags": [ "custom-fields" ], "summary": "Get the allow-list of a users custom field", "operationId": "get-custom-field-allowed-users", "parameters": [ { "type": "integer", "description": "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.CustomFieldAllowedUsers" } }, "400": { "description": "Not a users field", "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": "Replaces the member ids a users custom field can be set to. An empty list removes the restriction. Existing values outside the list are kept. At most 1000 ids; larger lists are rejected with 422. Ids not already on the list must be active or invited workspace members.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "custom-fields" ], "summary": "Replace the allow-list of a users custom field", "operationId": "replace-custom-field-allowed-users", "parameters": [ { "type": "integer", "description": "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": "Allowed users payload", "name": "allowed_users", "in": "body", "required": true, "schema": { "$ref": "#/definitions/customfield.AllowedUsersPayload" } } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.CustomFieldAllowedUsers" } }, "400": { "description": "Invalid request or not a users field", "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": "Allow-list changed concurrently", "schema": { "$ref": "#/definitions/response.Error" } }, "422": { "description": "Maximum number of allowed users 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": { "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}/designations": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the designations defined in the workspace.", "produces": [ "application/json" ], "tags": [ "designations" ], "summary": "List workspace designations", "operationId": "list-workspace-designations", "parameters": [ { "type": "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 designation IDs", "name": "designation_id", "in": "query" }, { "type": "string", "description": "filter by designation 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", "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_Trait" } }, "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 one designation in the workspace.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "designations" ], "summary": "Create a workspace designation", "operationId": "create-workspace-designation", "parameters": [ { "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": "Designation payload", "name": "designation", "in": "body", "required": true, "schema": { "$ref": "#/definitions/designation.CreateDesignationPayload" } } ], "responses": { "201": { "description": "Designation created successfully", "schema": { "$ref": "#/definitions/models.Trait" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Designation name already used", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/designations/bulk": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Creates designations in the workspace. The call is atomic.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "designations" ], "summary": "Create workspace designations", "operationId": "bulk-create-workspace-designations", "parameters": [ { "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": "Designations payload", "name": "designations", "in": "body", "required": true, "schema": { "$ref": "#/definitions/designation.CreateDesignationsRequest" } } ], "responses": { "201": { "description": "Designations created successfully", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Trait" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Designation name already used", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Soft-deletes designations. Unknown IDs are skipped unless all_or_none is set. Members assigned to them lose them.", "produces": [ "application/json" ], "tags": [ "designations" ], "summary": "Delete workspace designations", "operationId": "bulk-delete-workspace-designations", "parameters": [ { "type": "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": "designation IDs to delete", "name": "ids", "in": "query", "required": true }, { "type": "boolean", "description": "fail the whole call if any ID is unknown, instead of skipping it", "name": "all_or_none", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "type": "array", "items": { "type": "integer" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Designation not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Renames designations. Unknown IDs are skipped unless all_or_none is set.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "designations" ], "summary": "Update workspace designations", "operationId": "bulk-update-workspace-designations", "parameters": [ { "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": "Designations payload", "name": "designations", "in": "body", "required": true, "schema": { "$ref": "#/definitions/designation.UpdateDesignationsRequest" } } ], "responses": { "200": { "description": "Designations updated successfully", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Trait" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Designation not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Designation name already used", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/designations/members": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Applies the add and remove lists in one transaction. A pair may not appear in both.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "designations" ], "summary": "Assign and clear workspace designations", "operationId": "update-workspace-designation-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 }, { "description": "Members payload", "name": "members", "in": "body", "required": true, "schema": { "$ref": "#/definitions/designation.UpdateMembersRequest" } } ], "responses": { "200": { "description": "Members assigned successfully", "schema": { "type": "array", "items": { "$ref": "#/definitions/designation.Member" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Designation not found, or member does not hold it", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/designations/{designation_id}": { "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Soft-deletes one designation. Members assigned to it lose it.", "produces": [ "application/json" ], "tags": [ "designations" ], "summary": "Delete a workspace designation", "operationId": "delete-workspace-designation", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "designation ID", "name": "designation_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": "Designation not found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "patch": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Renames one designation.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "designations" ], "summary": "Update a workspace designation", "operationId": "update-workspace-designation", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "designation ID", "name": "designation_id", "in": "path", "required": true }, { "description": "Designation payload", "name": "designation", "in": "body", "required": true, "schema": { "$ref": "#/definitions/designation.UpdateDesignationRequest" } } ], "responses": { "200": { "description": "Designation updated successfully", "schema": { "$ref": "#/definitions/models.Trait" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Designation not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Designation name already used", "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.PreviewPayload" } } ], "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. A change to project_ids, task_ids, tag_ids, client_ids, billable, or weekdays on an active goal triggers a warehouse refresh and the response has is_syncing: true. A change to recurrence, monthly_anchor, or start_date restarts the goal's streak bookkeeping (previous_streak, best_streak, periods_met, last_notified_at reset); on an active goal this also triggers a warehouse refresh, but on an inactive goal no refresh is triggered since the warehouse never observes an inactive goal's edits.", "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" } }, "409": { "description": "Goal was modified concurrently -- re-fetch and retry", "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}/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, project_id, tag_ids and billable are all optional, but at least one is required. Supplying both task_id and project_id attaches the resulting time entry to the task and uses the project as an explicit override. tag_ids and billable are stamped onto the matched entry: a non-null tag_ids replaces its tags (an empty array clears them), and a non-null billable sets billable manually, subject to the workspace billable-override policy. A rule carrying only tag_ids and/or billable is valid and still lets the fuzzy suggestion resolve the task and project.", "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, target and stamped attributes of an existing mapping rule. task_id, project_id, tag_ids and billable are all optional, but at least one is required; any omitted field is cleared. Supplying both task_id and project_id attaches the resulting time entry to the task and uses the project as an explicit override. tag_ids and billable are stamped onto the matched entry: a non-null tag_ids replaces its tags (an empty array clears them), and a non-null billable sets billable manually, subject to the workspace billable-override policy.", "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/push-target": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns the single connected calendar that receives the user's Focus planned tasks, or null when none is set.", "produces": [ "application/json" ], "tags": [ "calendar" ], "summary": "Get the calendar push target", "operationId": "calendar-push-target-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 } ], "responses": { "200": { "description": "The stored push target, or null", "schema": { "$ref": "#/definitions/pushtarget.Target" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Sets the single connected calendar that receives the user's Focus planned tasks. The calendar must belong to an integration owned by the caller and that integration must have write scope. Requires the calendar_push_planned_entries beta flag.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "calendar" ], "summary": "Set the calendar push target", "operationId": "calendar-push-target-set", "parameters": [ { "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": "Push target payload", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/calendar.pushTargetRequest" } } ], "responses": { "200": { "description": "The stored push target", "schema": { "$ref": "#/definitions/pushtarget.Target" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "feature_not_enabled: the calendar_push_planned_entries beta flag is off for this user", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "not_found: the integration or calendar is not owned by the caller", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "calendar_write_scope_missing: the integration lacks write scope, or calendar_not_selected: the calendar is not selected", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "delete": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Clears the single connected calendar that receives the user's Focus planned tasks. Idempotent.", "produces": [ "text/plain" ], "tags": [ "calendar" ], "summary": "Clear the calendar push target", "operationId": "calendar-push-target-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 } ], "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/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. Runs to completion once authorized, even if the client disconnects. The response waits a few seconds for the cleanup of the entries the integration synced, so a refetch on it usually sees the result.", "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 are retained. Either way, entries that outlive the disconnect have their calendar_event_id cleared.", "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. Setting selected to false also cleans up the time entries the calendar synced, runs to completion once authorized even if the client disconnects, and waits a few seconds for that cleanup before responding.", "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" } } } } }, "/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": "boolean", "description": "Only projects where the caller has an active project role, directly or through a team; normal visibility and lifecycle filters still apply.", "name": "member_only", "in": "query" }, { "type": "boolean", "description": "Include permission-filtered task counts for this project page, including draft or completed projects returned by the project filters; no_project_task_count is returned on page 1. Off by default.", "name": "include_task_counts", "in": "query" }, { "type": "boolean", "description": "Include eligible unified-picker parent-task group counts for this project page; no_project_picker_parent_group_count is returned on page 1. Off by default.", "name": "include_picker_parent_group_counts", "in": "query" }, { "type": "boolean", "description": "Filter counted tasks by archived state; omit to include both.", "name": "task_archived", "in": "query" }, { "type": "boolean", "description": "Filter counted tasks by recurring state, matching the tasks endpoint.", "name": "task_recurring", "in": "query" }, { "type": "array", "items": { "enum": [ "tracked", "not_tracked", "active", "done" ], "type": "string" }, "collectionFormat": "csv", "description": "Filter counted tasks by state.", "name": "task_state", "in": "query" }, { "type": "array", "items": { "type": "string" }, "collectionFormat": "csv", "description": "Filter counted tasks by source, matching the tasks endpoint.", "name": "task_source", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Count tasks assigned to these users, OR tasks assigned directly to task_assignee_team_id.", "name": "task_assignee_user_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "Count tasks assigned directly to these teams; does not expand team membership.", "name": "task_assignee_team_id", "in": "query" }, { "type": "boolean", "description": "Also count tasks or picker parent groups with no direct assignee and no live team assignment; combined with task_assignee_user_id/task_assignee_team_id as an OR for task counts.", "name": "task_include_unassigned", "in": "query" }, { "type": "string", "description": "Filter counted tasks by name independently of the project name filter.", "name": "task_name", "in": "query" }, { "type": "string", "format": "date", "description": "Repeats of a recurring task dated after this date + task_occurrence_window_days are not counted; earlier ones are. Default: today (UTC).", "name": "task_occurrence_window_date", "in": "query" }, { "type": "integer", "description": "Days after task_occurrence_window_date, 0–31. Default: 7.", "name": "task_occurrence_window_days", "in": "query" }, { "type": "integer", "description": "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/project.ListResponse" } }, "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. Omitted private inherits the parent project visibility, or the workspace default when there is no parent. Explicit values retain normal authorization.", "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" } }, "404": { "description": "Project not found or not accessible", "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": "boolean", "description": "also return recurring project templates alongside their instances (default false)", "name": "include_recurring_series", "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. With an rrule the clone is a new recurring series parent (is_template + rrule) instead; the template itself is unchanged.", "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/project.ClonedProjectResponse" } }, "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/project.ClonedProjectResponse" } }, "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" } }, "422": { "description": "A duplicated task violates the workspace's required fields", "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/project.ClonedProjectResponse" } }, "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).\nCompleted or archived tasks and archived projects are excluded from suggestions.\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": "boolean", "description": "Also match tasks with no direct assignee and no live team assignment; combined with assignee_user_id/assignee_team_id as an OR", "name": "include_unassigned", "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", "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 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": "Only tasks without a project or in a live, non-archived, non-completed, non-template, non-draft project.", "name": "active_project", "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": "string", "format": "date", "description": "Repeats of a recurring task dated after this date + occurrence_window_days are hidden; earlier ones show. Default: today (UTC).", "name": "occurrence_window_date", "in": "query" }, { "type": "integer", "description": "Days after occurrence_window_date, 0–31. Default: 7. Ignored with end_date or active_by_date.", "name": "occurrence_window_days", "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": [ "tracked", "not_tracked", "active", "done" ], "type": "string" }, "collectionFormat": "csv", "description": "filter by state", "name": "state", "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. Omitted private inherits the parent task, then project visibility, then the effective workspace default, gated by private-feature access. Project-less tasks default to private when the role requires it and the plan permits it.", "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.CreatePayloadWithRecurringRule" } } ], "responses": { "201": { "description": "Task created successfully", "schema": { "$ref": "#/definitions/models.Task" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Not available on the current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions, or repeating tasks are not enabled (error=feature_not_enabled)", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "The task's project changed while the task was being made to repeat; try again (error=task_changed_while_repeating)", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } }, "503": { "description": "Beta features service unavailable (error=beta_features_unavailable)", "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. Omitted private uses the same context, workspace default, and role rules as single-task creation.", "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" } }, "402": { "description": "Not available on the current plan", "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" } }, "402": { "description": "Not available on the current plan", "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. `position` and `after_task_id` are mutually exclusive, and `after_task_id` may not name another task updated in the same request: items are applied in ascending task id and each anchor resolves against committed state.", "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" } }, "402": { "description": "Not available on the current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Tags are required, and removing the tags would leave time entries without tags (error=would_leave_time_entries_without_tags)", "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. An ID\nwith no task behind it is skipped rather than failing the batch;\narchive a single task if you need a missing one reported.", "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" } }, "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" } }, "402": { "description": "Not available on the current plan", "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. An ID\nwith no archived task behind it is skipped rather than failing the\nbatch; unarchive a single task if you need a missing one reported.", "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" } }, "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": "Deprecated: use `GET /organizations/{organization_id}/workspaces/{workspace_id}/calendar/events`, which is identical. This path is retained only for clients that cannot be updated, and will be removed once its traffic reaches zero. 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", "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": "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": "Deprecated: use `POST /organizations/{organization_id}/workspaces/{workspace_id}/calendar/sync`, which is identical. This path is retained only for clients that cannot be updated, and will be removed once its traffic reaches zero. Sync a list of tasks based on calendar events.\nPass `skip_provider_refresh=true` to skip the live calendar provider refresh before syncing (e.g. for a caller that knows the CalendarsEvents cache already has current provider data).", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Sync tasks by calendar range", "operationId": "put-tasks-calendar-range", "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": "string", "description": "from timestamp", "name": "date_from", "in": "query", "required": true }, { "type": "string", "description": "to timestamp", "name": "date_to", "in": "query", "required": true }, { "type": "boolean", "description": "skip the live calendar provider refresh before syncing (default false: refresh happens)", "name": "skip_provider_refresh", "in": "query" } ], "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.\nThe X-Timeline-Fetch-Trigger request header says why the Timeline is reading. On an\norganization whose Timeline views are limited it decides what is counted, never what\nis served: the allowance is enforced on every read whatever it says.\nAbsent, view or navigation is a Timeline view and counts against the allowance.\nscroll, zoom, pagination and lane ask to be treated as a continuation of a view\nalready counted, which the server grants only while this user still holds the\nin-progress marker a counted view leaves behind (30 minutes, and only another\ncounted view renews it). With no marker the read is counted as the view it is;\nwith one it is served even after the allowance is spent.", "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" }, { "type": "array", "items": { "enum": [ "none", "low", "medium", "high" ], "type": "string" }, "collectionFormat": "csv", "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; requires the team-reports grant (manage_team_reports, or view_team_members_data_reports on a team); otherwise ignored and listed in X-Filters-Dropped", "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); without the team-reports grant (manage_team_reports, or view_team_members_data_reports on a team) only teams the caller belongs to apply; every other value (including the no-team value) is ignored and listed in X-Filters-Dropped", "name": "team_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by assignee member-tag IDs (resolves to member user IDs); requires the team-reports grant (manage_team_reports, or view_team_members_data_reports on a team); otherwise ignored and listed in X-Filters-Dropped", "name": "user_tag_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by group IDs; on /users these are user IDs and the param requires the team-reports grant (manage_team_reports, or view_team_members_data_reports on a team); otherwise ignored and listed in X-Filters-Dropped", "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 view_workspace_user_custom_fields.", "name": "user_cf_filter", "in": "query" }, { "enum": [ "view", "navigation", "scroll", "zoom", "pagination", "lane" ], "type": "string", "description": "why the Timeline is reading; decides what is counted, never what is served", "name": "X-Timeline-Fetch-Trigger", "in": "header" } ], "responses": { "200": { "description": "Lanes in data, one per requested project in request order, each answered completely", "schema": { "$ref": "#/definitions/taskgroup.projectTaskGroupsResponse" }, "headers": { "X-Filters-Dropped": { "type": "string", "description": "comma-separated query params ignored for lack of the team-reports grant (assignee_user_id, team_id, user_tag_id, group_id); team_id is listed when any of its values was ignored; absent when nothing was dropped" }, "X-Filters-Dropped-Feature": { "type": "string", "description": "the plan feature that unlocks them (team_reports); only when the reason is feature_not_available" }, "X-Filters-Dropped-Reason": { "type": "string", "description": "why they were dropped: feature_not_available (plan) or permission (role); only with X-Filters-Dropped" }, "X-Timeline-Views-Count": { "type": "string", "description": "Timeline views used in the open allowance window. Only for limited organizations, and only on a read that counted a view: a read that counted nothing omits all three rather than publish a count taken before another request moved the counter" }, "X-Timeline-Views-Limit": { "type": "string", "description": "Timeline views allowed per window, a month long and opened by the first view; only with X-Timeline-Views-Count" }, "X-Timeline-Views-Reset-At": { "type": "string", "description": "RFC3339 instant the allowance resets. Best-effort: sent with X-Timeline-Views-Count when the window is known, and omitted when the read that opened it could not re-read the counter, so a count can arrive without it" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Control-arm Timeline access unavailable (feature_not_available; timelines), or the Timeline views allowance is spent (timeline_views_quota_exceeded)", "schema": { "$ref": "#/definitions/response.Error" }, "headers": { "X-Timeline-Views-Count": { "type": "string", "description": "Only on quota refusal: Timeline views used, equal to the limit; omitted for control-arm feature denial" }, "X-Timeline-Views-Limit": { "type": "string", "description": "Timeline views allowed per window; only with X-Timeline-Views-Count" }, "X-Timeline-Views-Reset-At": { "type": "string", "description": "RFC3339 instant the allowance resets, which is when the refused read starts working again" } } }, "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.\nThe X-Timeline-Fetch-Trigger request header says why the Timeline is reading. On an\norganization whose Timeline views are limited it decides what is counted, never what\nis served: the allowance is enforced on every read whatever it says.\nAbsent, view or navigation is a Timeline view and counts against the allowance.\nscroll, zoom, pagination and lane ask to be treated as a continuation of a view\nalready counted, which the server grants only while this user still holds the\nin-progress marker a counted view leaves behind (30 minutes, and only another\ncounted view renews it). With no marker the read is counted as the view it is;\nwith one it is served even after the allowance is spent.", "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. Without the team-reports grant (manage_team_reports, or view_team_members_data_reports on a team) only lanes for teams the caller belongs to are answered; every other lane (including the no-team lane) is ignored and team_id is listed in X-Filters-Dropped", "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" }, { "type": "array", "items": { "enum": [ "none", "low", "medium", "high" ], "type": "string" }, "collectionFormat": "csv", "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; requires the team-reports grant (manage_team_reports, or view_team_members_data_reports on a team); otherwise ignored and listed in X-Filters-Dropped", "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); requires the team-reports grant; otherwise ignored and listed in X-Filters-Dropped", "name": "user_tag_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by group IDs (user IDs on this read); requires the team-reports grant; otherwise ignored and listed in X-Filters-Dropped", "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 view_workspace_user_custom_fields.", "name": "user_cf_filter", "in": "query" }, { "enum": [ "view", "navigation", "scroll", "zoom", "pagination", "lane" ], "type": "string", "description": "why the Timeline is reading; decides what is counted, never what is served", "name": "X-Timeline-Fetch-Trigger", "in": "header" } ], "responses": { "200": { "description": "Lanes in data for the answered teams only, in request order, each answered completely; ignored lanes (see team_id) are omitted, so key lanes by team_id, not by index", "schema": { "$ref": "#/definitions/taskgroup.teamTaskGroupsResponse" }, "headers": { "X-Filters-Dropped": { "type": "string", "description": "comma-separated query params ignored for lack of the team-reports grant (assignee_user_id, team_id — the lane selection — user_tag_id, group_id); team_id is listed when any of its values or lanes was ignored; absent when nothing was dropped" }, "X-Filters-Dropped-Feature": { "type": "string", "description": "the plan feature that unlocks them (team_reports); only when the reason is feature_not_available" }, "X-Filters-Dropped-Reason": { "type": "string", "description": "why they were dropped: feature_not_available (plan) or permission (role); only with X-Filters-Dropped" }, "X-Timeline-Views-Count": { "type": "string", "description": "Timeline views used in the open allowance window. Only for limited organizations, and only on a read that counted a view: a read that counted nothing omits all three rather than publish a count taken before another request moved the counter" }, "X-Timeline-Views-Limit": { "type": "string", "description": "Timeline views allowed per window, a month long and opened by the first view; only with X-Timeline-Views-Count" }, "X-Timeline-Views-Reset-At": { "type": "string", "description": "RFC3339 instant the allowance resets. Best-effort: sent with X-Timeline-Views-Count when the window is known, and omitted when the read that opened it could not re-read the counter, so a count can arrive without it" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Control-arm Timeline access unavailable (feature_not_available; timelines), or the Timeline views allowance is spent (timeline_views_quota_exceeded)", "schema": { "$ref": "#/definitions/response.Error" }, "headers": { "X-Timeline-Views-Count": { "type": "string", "description": "Only on quota refusal: Timeline views used, equal to the limit; omitted for control-arm feature denial" }, "X-Timeline-Views-Limit": { "type": "string", "description": "Timeline views allowed per window; only with X-Timeline-Views-Count" }, "X-Timeline-Views-Reset-At": { "type": "string", "description": "RFC3339 instant the allowance resets, which is when the refused read starts working again" } } }, "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\nThe X-Timeline-Fetch-Trigger request header says why the Timeline is reading. On an\norganization whose Timeline views are limited it decides what is counted, never what\nis served: the allowance is enforced on every read whatever it says.\nAbsent, view or navigation is a Timeline view and counts against the allowance.\nscroll, zoom, pagination and lane ask to be treated as a continuation of a view\nalready counted, which the server grants only while this user still holds the\nin-progress marker a counted view leaves behind (30 minutes, and only another\ncounted view renews it). With no marker the read is counted as the view it is;\nwith one it is served even after the allowance is spent.", "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; projects requires view_timeline_projects_group and tags requires manage_timeline_grouping", "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" }, { "type": "array", "items": { "enum": [ "none", "low", "medium", "high" ], "type": "string" }, "collectionFormat": "csv", "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; requires the team-reports grant (manage_team_reports, or view_team_members_data_reports on a team); otherwise ignored and listed in X-Filters-Dropped", "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); without the team-reports grant (manage_team_reports, or view_team_members_data_reports on a team) only teams the caller belongs to apply; every other value (including the no-team value) is ignored and listed in X-Filters-Dropped", "name": "team_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by assignee member-tag IDs (resolves to member user IDs); requires the team-reports grant (manage_team_reports, or view_team_members_data_reports on a team); otherwise ignored and listed in X-Filters-Dropped", "name": "user_tag_id", "in": "query" }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "filter by group IDs; on /users these are user IDs and the param requires the team-reports grant (manage_team_reports, or view_team_members_data_reports on a team); otherwise ignored and listed in X-Filters-Dropped", "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 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" }, { "enum": [ "view", "navigation", "scroll", "zoom", "pagination", "lane" ], "type": "string", "description": "why the Timeline is reading; decides what is counted, never what is served", "name": "X-Timeline-Fetch-Trigger", "in": "header" } ], "responses": { "200": { "description": "Tasks grouped by type", "schema": { "$ref": "#/definitions/taskgroup.taskGroupsResponse" }, "headers": { "X-Filters-Dropped": { "type": "string", "description": "comma-separated query params ignored for lack of the team-reports grant (assignee_user_id, team_id, user_tag_id, group_id); team_id is listed when any of its values was ignored; absent when nothing was dropped" }, "X-Filters-Dropped-Feature": { "type": "string", "description": "the plan feature that unlocks them (team_reports); only when the reason is feature_not_available" }, "X-Filters-Dropped-Reason": { "type": "string", "description": "why they were dropped: feature_not_available (plan) or permission (role); only with X-Filters-Dropped" }, "X-Timeline-Views-Count": { "type": "string", "description": "Timeline views used in the open allowance window. Only for limited organizations, and only on a read that counted a view: a read that counted nothing omits all three rather than publish a count taken before another request moved the counter" }, "X-Timeline-Views-Limit": { "type": "string", "description": "Timeline views allowed per window, a month long and opened by the first view; only with X-Timeline-Views-Count" }, "X-Timeline-Views-Reset-At": { "type": "string", "description": "RFC3339 instant the allowance resets. Best-effort: sent with X-Timeline-Views-Count when the window is known, and omitted when the read that opened it could not re-read the counter, so a count can arrive without it" } } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Grouping or control-arm Timeline access unavailable (feature_not_available; timelines for control), or the Timeline views allowance is spent (timeline_views_quota_exceeded)", "schema": { "$ref": "#/definitions/response.Error" }, "headers": { "X-Timeline-Views-Count": { "type": "string", "description": "Only on quota refusal: Timeline views used, equal to the limit; omitted for control-arm feature denial" }, "X-Timeline-Views-Limit": { "type": "string", "description": "Timeline views allowed per window; only with X-Timeline-Views-Count" }, "X-Timeline-Views-Reset-At": { "type": "string", "description": "RFC3339 instant the allowance resets, which is when the refused read starts working again" } } }, "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.\nA move that changes the task's own fields (dates, project,\nassignees, tags) takes the same modify permission as editing the\ntask: such a task is a 404 when the caller cannot see it and a 403\nwhen they may not modify it. Entries that only reposition a task —\nsame lane, same dates — rewrite ordering weights alone and, like\nremoves, stay on the workspace permission.", "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; tags requires the manage_timeline_grouping permission", "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" } }, "402": { "description": "Feature not available on the current plan", "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/picker/groups": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns eligible parent-task groups with matching counts. Matching descendants are previewed on search (up to five per group). When search matches the project, client, or visible parent, every eligible child matches; otherwise only child-name matches count. Show N when matching_child_count equals eligible_child_count, or M of N when it is lower. Omit project_id for all accessible projects; pass without_project=true for projectless tasks.", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "List task groups for the unified picker", "operationId": "list-picker-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 }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "query" }, { "type": "boolean", "description": "select projectless tasks", "name": "without_project", "in": "query" }, { "type": "boolean", "description": "include only pinned projects", "name": "pinned_only", "in": "query" }, { "type": "boolean", "description": "include tasks with no direct user or live team assignment", "name": "include_unassigned", "in": "query" }, { "type": "string", "description": "search task, parent, project, and client names", "name": "search", "in": "query" }, { "type": "boolean", "description": "use Track-shaped project access", "name": "only_me", "in": "query" }, { "type": "string", "format": "date", "description": "Repeats of a recurring task dated after this date + occurrence_window_days are hidden; earlier ones show. Default: today (UTC).", "name": "occurrence_window_date", "in": "query" }, { "type": "integer", "description": "Days after occurrence_window_date, 0–31. Default: 7.", "name": "occurrence_window_days", "in": "query" }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/task.PickerGroupPage" } }, "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}/tasks/picker/parents/{parent_task_id}/children": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a page of selectable children with eligible and search-matching totals for one project scope. Pass project_id or without_project=true. A visible parent, project, or client name match includes all eligible children; otherwise only matching child names are returned.", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "List eligible children for a unified picker task group", "operationId": "list-picker-task-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": "parent task ID", "name": "parent_task_id", "in": "path", "required": true }, { "type": "integer", "description": "project ID", "name": "project_id", "in": "query" }, { "type": "boolean", "description": "select projectless tasks", "name": "without_project", "in": "query" }, { "type": "boolean", "description": "include tasks with no direct user or live team assignment", "name": "include_unassigned", "in": "query" }, { "type": "string", "description": "search child, visible parent, project, and client names", "name": "search", "in": "query" }, { "type": "boolean", "description": "use Track-shaped project access", "name": "only_me", "in": "query" }, { "type": "integer", "description": "page number", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/task.PickerChildPage" } }, "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}/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 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": "Only tasks without a project or in a live, non-archived, non-completed, non-template, non-draft project.", "name": "active_project", "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": "string", "format": "date", "description": "Repeats of a recurring task dated after this date + occurrence_window_days are hidden; earlier ones show. Default: today (UTC).", "name": "occurrence_window_date", "in": "query" }, { "type": "integer", "description": "Days after occurrence_window_date, 0–31. Default: 7. Ignored with end_date or active_by_date.", "name": "occurrence_window_days", "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": [ "tracked", "not_tracked", "active", "done" ], "type": "string" }, "collectionFormat": "csv", "description": "filter by state", "name": "state", "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" } }, "402": { "description": "Not available on the current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Tags are required, and removing the tags would leave time entries without tags (error=would_leave_time_entries_without_tags)", "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" } }, "402": { "description": "Not available on the current plan", "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. `position` (an ordinal rank) and `after_task_id` (the neighbour to land behind) are mutually exclusive.", "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" } }, "402": { "description": "Not available on the current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions, or repeating tasks are not enabled (error=feature_not_enabled)", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Task not found", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "Tags are required, and removing the tags would leave time entries without tags (error=would_leave_time_entries_without_tags); the task already repeats (error=task_already_repeats); the task changed while it was being made to repeat, try again (error=task_changed_while_repeating)", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } }, "503": { "description": "Beta features service unavailable (error=beta_features_unavailable)", "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" } }, "402": { "description": "Payment Required", "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" } }, "402": { "description": "Payment Required", "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" } }, "402": { "description": "Payment Required", "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 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}/occurrences": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Declared for PR 5B: materializes exactly one occurrence (O) of the series task at the requested slot. Until the contract lands, every request is rejected with recurring_occurrence_write_not_supported; the path is reserved so clients get the declared validation error instead of a 404.\nThe planned opt-in response shape is declared in docs/recurring-pr2a-additive-schema.md: `return_occurrence=true` answers 200 with the exact O, the default stays 204.", "produces": [ "application/json" ], "tags": [ "tasks" ], "summary": "Create one occurrence of a recurring series", "operationId": "create-recurring-occurrence", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "integer", "description": "series task ID", "name": "task_id", "in": "path", "required": true }, { "type": "boolean", "description": "declared for PR 5B: answer 200 with the materialized occurrence instead of the default 204", "name": "return_occurrence", "in": "query" } ], "responses": { "204": { "description": "Occurrence materialized (declared; not enabled yet)" }, "400": { "description": "Declared but not enabled yet (error=recurring_occurrence_write_not_supported)", "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}/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-entries": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of time-entries based on the provided workspace ID, task ID and filter params. With `include_subtasks=true`, a task that sums subtask totals also lists the entries of the subtasks whose time is summed into its totals, each under its own `task_id`; a task that does not sum subtask totals lists its own entries only, whatever the flag.", "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": "boolean", "description": "also list entries of the subtasks summed into this task's totals (default false)", "name": "include_subtasks", "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" } }, { "type": "integer", "description": "DECLARED FOR PR 4/12, NOT ENABLED: scope the planned-time operation to a recurring series. Any supplied value is rejected until the implementing PR lands.", "name": "from_recurring_task_id", "in": "query" }, { "type": "boolean", "description": "DECLARED FOR PR 12, NOT ENABLED: answer 200 with the exact occurrence instead of the default 204. Any active use is rejected until the implementing PR lands.", "name": "return_occurrence", "in": "query" } ], "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" } }, { "type": "integer", "description": "DECLARED FOR PR 4/12, NOT ENABLED: scope the planned-time operation to a recurring series. Any supplied value is rejected until the implementing PR lands.", "name": "from_recurring_task_id", "in": "query" }, { "type": "boolean", "description": "DECLARED FOR PR 12, NOT ENABLED: answer 200 with the exact occurrence instead of the default 204. Any active use is rejected until the implementing PR lands.", "name": "return_occurrence", "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 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 }, { "type": "integer", "description": "DECLARED FOR PR 4/12, NOT ENABLED: scope the planned-time operation to a recurring series. Any supplied value is rejected until the implementing PR lands.", "name": "from_recurring_task_id", "in": "query" }, { "type": "boolean", "description": "DECLARED FOR PR 12, NOT ENABLED: answer 200 with the exact occurrence instead of the default 204. Any active use is rejected until the implementing PR lands.", "name": "return_occurrence", "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 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" } }, { "type": "integer", "description": "DECLARED FOR PR 4/12, NOT ENABLED: scope the planned-time operation to a recurring series. Any supplied value is rejected until the implementing PR lands.", "name": "from_recurring_task_id", "in": "query" }, { "type": "boolean", "description": "DECLARED FOR PR 12, NOT ENABLED: answer 200 with the exact occurrence instead of the default 204. Any active use is rejected until the implementing PR lands.", "name": "return_occurrence", "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 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}/unarchive": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Unarchives a task, and all its 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-entries": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns a list of time-entries based on the provided workspace ID and filter params.\nOnly the caller's own time entries are returned, whatever their role. To read other members' time, use the reports query endpoint (POST /reports/workspaces/{workspace_id}/query). For guests, entries on tasks or projects they cannot access, and entries with neither, are also left out.\nReturns every entry that overlaps the `date_from`–`date_to` range: a tracked entry by its `start` and `duration`, a planned-only entry by its `planned_start` and `planned_duration`. A running timer has no `duration` yet, so it is returned only if it started within the range.\nEntries without a task are left out unless `include_taskless=true`.\nResults are paginated; the response has no total count, so keep requesting pages until one returns no entries. A page can hold fewer than `per_page` entries while more pages follow. For guests, even an empty page can be followed by more; use the stream endpoint to read a whole range.", "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": "range start, as an RFC 3339 timestamp, e.g. 2026-09-01T00:00:00Z (percent-encode a + offset)", "name": "date_from", "in": "query", "required": true }, { "type": "string", "description": "range end, as an RFC 3339 timestamp, e.g. 2026-09-30T23:59:59Z", "name": "date_to", "in": "query", "required": true }, { "type": "integer", "description": "only entries of this task", "name": "task_id", "in": "query" }, { "type": "integer", "description": "only entries whose task has this status", "name": "status_id", "in": "query" }, { "type": "integer", "description": "only entries of this project (the entry's own project, else its task's)", "name": "project_id", "in": "query" }, { "enum": [ "activity", "break" ], "type": "string", "description": "time entry type", "name": "type", "in": "query" }, { "type": "integer", "description": "page number, starting at 1 (default 1)", "name": "page", "in": "query" }, { "type": "integer", "description": "results per page (default 20, max 100)", "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": "sort columns, repeated or comma-separated; prefix - for descending. Ties are broken by id", "name": "order_by", "in": "query" }, { "type": "boolean", "description": "true for archived entries only, false for unarchived only; omit for both", "name": "archived", "in": "query" }, { "type": "boolean", "description": "include entries without a task (default false)", "name": "include_taskless", "in": "query" }, { "type": "boolean", "description": "true for entries on a completed project only, false for non-completed only; omit for both. An entry counts as completed when its own project or its task's project is completed", "name": "project_completed", "in": "query" }, { "type": "boolean", "description": "true for entries on a draft project only, false for non-draft only; omit for both. Checks the same two projects as project_completed", "name": "project_draft", "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" } }, { "type": "integer", "description": "DECLARED FOR PR 4/12, NOT ENABLED: scope the planned-time operation to a recurring series. Any supplied value is rejected until the implementing PR lands.", "name": "from_recurring_task_id", "in": "query" }, { "type": "boolean", "description": "DECLARED FOR PR 12, NOT ENABLED: answer 200 with the exact occurrence instead of the default 204. Any active use is rejected until the implementing PR lands.", "name": "return_occurrence", "in": "query" } ], "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": { "201": { "description": "Time entries created successfully", "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" } }, "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/groups/users": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns one group per workspace member on the requested page.\nPagination walks the members sorted by name, not the time entries.\nEach group holds the member's planned time entries that mirror a\ncalendar event (calendar_event_id set). An entry that has been\ntracked stays in its group and carries start and duration; entries\nwithout them are not tracked yet.\nAn entry is in range when the span from planned_start to\nplanned_start plus planned_duration overlaps the date range, and it\nkeeps that planned placement after tracking.\nSpans longer than 31 days that started before the lookback are omitted.\nThe response only holds members the caller may see. view_teams_timeline\nshows everyone. Team leads see their team members and themselves.\nOthers see only themselves.\nA member with no matching entries still gets a group with an empty\ntime_entries array.", "produces": [ "application/json" ], "tags": [ "time-entry-groups" ], "summary": "Gets calendar-linked planned time entries grouped by user", "operationId": "get-time-entry-groups-users", "parameters": [ { "type": "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": "range start (inclusive)", "name": "start_date", "in": "query", "required": true }, { "type": "string", "format": "date", "description": "range end (inclusive)", "name": "end_date", "in": "query", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "restrict the groups to these user IDs", "name": "user_id", "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": "Time entries grouped by user", "schema": { "$ref": "#/definitions/timeentrygroup.timeEntryGroupsResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Insufficient permissions", "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" } } } } }, "/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.\nOnly the caller's own time entries are returned, whatever their role. To read other members' time, use the reports query endpoint (POST /reports/workspaces/{workspace_id}/query). For guests, entries on tasks or projects they cannot access, and entries with neither, are also left out.\nReturns every entry that overlaps the `date_from`–`date_to` range: a tracked entry by its `start` and `duration`, a planned-only entry by its `planned_start` and `planned_duration`. A running timer has no `duration` yet, so it is returned only if it started within the range.\nEntries without a task are left out unless `include_taskless=true`.\nReturns every matching entry as a single JSON array, without pagination.", "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": "range start, as an RFC 3339 timestamp, e.g. 2026-09-01T00:00:00Z (percent-encode a + offset)", "name": "date_from", "in": "query", "required": true }, { "type": "string", "description": "range end, as an RFC 3339 timestamp, e.g. 2026-09-30T23:59:59Z", "name": "date_to", "in": "query", "required": true }, { "type": "integer", "description": "only entries of this task", "name": "task_id", "in": "query" }, { "type": "integer", "description": "only entries whose task has this status", "name": "status_id", "in": "query" }, { "type": "integer", "description": "only entries of this project (the entry's own project, else its task's)", "name": "project_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": "sort columns, repeated or comma-separated; prefix - for descending. Ties are broken by id", "name": "order_by", "in": "query" }, { "type": "boolean", "description": "true for archived entries only, false for unarchived only; omit for both", "name": "archived", "in": "query" }, { "type": "boolean", "description": "include entries without a task (default false)", "name": "include_taskless", "in": "query" }, { "type": "boolean", "description": "true for entries on a completed project only, false for non-completed only; omit for both. An entry counts as completed when its own project or its task's project is completed", "name": "project_completed", "in": "query" }, { "type": "boolean", "description": "true for entries on a draft project only, false for non-draft only; omit for both. Checks the same two projects as project_completed", "name": "project_draft", "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_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" } }, { "type": "integer", "description": "DECLARED FOR PR 4/12, NOT ENABLED: scope the planned-time operation to a recurring series. Any supplied value is rejected until the implementing PR lands.", "name": "from_recurring_task_id", "in": "query" }, { "type": "boolean", "description": "DECLARED FOR PR 12, NOT ENABLED: answer 200 with the exact occurrence instead of the default 204. Any active use is rejected until the implementing PR lands.", "name": "return_occurrence", "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 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 }, { "type": "integer", "description": "DECLARED FOR PR 4/12, NOT ENABLED: scope the planned-time operation to a recurring series. Any supplied value is rejected until the implementing PR lands.", "name": "from_recurring_task_id", "in": "query" }, { "type": "boolean", "description": "DECLARED FOR PR 12, NOT ENABLED: answer 200 with the exact occurrence instead of the default 204. Any active use is rejected until the implementing PR lands.", "name": "return_occurrence", "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 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" } }, { "type": "integer", "description": "DECLARED FOR PR 4/12, NOT ENABLED: scope the planned-time operation to a recurring series. Any supplied value is rejected until the implementing PR lands.", "name": "from_recurring_task_id", "in": "query" }, { "type": "boolean", "description": "DECLARED FOR PR 12, NOT ENABLED: answer 200 with the exact occurrence instead of the default 204. Any active use is rejected until the implementing PR lands.", "name": "return_occurrence", "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 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}/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 every setup they are or were enrolled in as a member whose span overlaps the window. An explicit `setup_id` narrows to that one setup. A discontinued setup (`end_date` in the past) stays in this scope while its periods overlap the window, so its retained history stays reachable; each row carries `setup_end_date` and `setup_discontinued` so clients can mark it. 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", "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", "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", "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/counts": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Returns how many timesheets fall in each approval status for the same scope, visibility and filters as listing timesheets. Each count equals the `X-Total-Count` the list returns for the same filters with `statuses` set to that one status. Every status is always present, zero when nothing matches. The `date_from`/`date_to` window follows the list's rules, including the 90-day limit.", "produces": [ "application/json" ], "tags": [ "timesheets" ], "summary": "Count timesheets visible to the caller per status", "operationId": "get-timesheet-status-counts", "parameters": [ { "type": "integer", "description": "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": "string", "description": "inclusive start of the window; every period overlapping it is counted (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 counted (YYYY-MM-DD)", "name": "date_to", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/timesheet.StatusCounts" } }, "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/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}/track-team-invites": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Grants the selected organization members the base Focus role in the workspace and emails each member who got it. Only members with a Track role and no Focus role in the workspace are eligible; the rest are reported as skipped. Members are processed one by one, and once the organization reaches its Focus seat limit the remaining members are reported as failed with max_count_of_users_reached. Requires the manage_organization_users permission.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "track-team-invites" ], "summary": "Bring Track teammates into Toggl 2.0", "operationId": "post-track-team-invites", "parameters": [ { "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": "Members to invite", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/trackteaminvite.InviteRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/trackteaminvite.Result" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "429": { "description": "Too Many Requests", "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) on the new entry, or on the running entry it would stop (error_values.time_entry_id names that entry)", "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. An integration is governed by its own policy row if the organization set one, otherwise by the organization-wide `__default__` row, and is unrestricted only when neither exists. 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.\nThe policy's `use_*` flags go further and govern what this endpoint will USE from the payload at all. They apply to what the EXTENSION supplies, not to what the entry ends up holding: with `use_project` off the payload's `project_name` is neither resolved nor used to narrow task matching — `resolution_strategy` degrades accordingly, so `name_project` is answered as `name` and reported as such — but a task the start MATCHES keeps its own project, and the entry derives from the task as always. With `use_task` off no task lookup runs at all: the entry is taskless, `match_reason` is `taskless_policy` rather than `taskless`, and `resolution_strategy` is `none`.\nA `project_name` that several live projects in the workspace share is reported as `project_ambiguous: true` and none is attached, rather than one being guessed. Under a project-scoped strategy (`name_project`, `name_project_tags`, or none given) the task lookup is skipped as well, since matching would choose a project for the user: the entry is taskless, `match_reason` is `taskless_ambiguous_project` rather than `taskless`, and `resolution_strategy` is `none`. `uri` and `name` starts still run their own lookup. Nothing is created for an ambiguous name even with `create_project_if_not_found`, since a third project would only deepen the collision. A name that exists only on a project this caller may not use is reported as `project_inaccessible: true` and likewise never created.\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 what happened, and `tags_dropped` covers the case the others cannot: tags that resolved but did not land on the entry, either because the write refused the override and was retried untagged, or because the path deliberately did not attempt it (`taskless_unauthorized`). Note that `tags_not_found` holds only names that never resolved or whose CREATION was denied — an attach denial leaves it empty, which is why `tags_dropped` exists. On a task-bound start the returned task's tags still show what it carries; on every taskless path that task is `null`, so `tags_dropped` is the only signal.\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. The same holds for `use_task: false`: in a task-required workspace that policy makes every extension start fail the constraint, because there is no path left that produces a task. The two settings are configured in different places, so an admin can reach that state without either screen showing the conflict.\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}": { "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 100 MB each, 300 MB per request). 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 100 MB each, 300 MB total)", "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 or request too large, invalid encoding, invalid file type, empty file, oversized record, too many columns)", "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, newest first, each with the names of its attached files. Rows are summaries: sample rows, headers, and dry-run samples are left out; GET uploads/{request_id} returns the full request.", "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" }, { "type": "array", "items": { "enum": [ "pending", "mapping", "ready", "importing", "completed", "completed_with_errors", "failed", "reverting", "reverted", "revert_failed" ], "type": "string" }, "collectionFormat": "csv", "description": "filter by status (repeatable); omit to list every status", "name": "status", "in": "query" } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/models.PageWithTotal-csv_UploadRequestSummaryResponse" } }, "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. A team the teams column names that already has access to a project keeps the role it has there. A task's teams column only matches teams already in this workspace, or ones this import creates from the member teams column; it never creates a team, and a name no team has, or a team tasks can't be assigned to, is skipped with a warning while the task still imports. 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 blank or unmapped time-entry task creates a taskless entry, optionally linked to its resolved project; a non-empty task reference that cannot be resolved still stops the row. 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 and teams 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, or another upload in this workspace is pending, mapping, ready, importing or reverting", "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 100 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 100 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}": { "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}/download": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Streams the CSV exactly as the importer stored it. A file uploaded in Windows-1252 was converted to UTF-8 on upload and comes back as UTF-8. Available for any upload that has not been canceled, whatever its status.", "produces": [ "text/csv" ], "tags": [ "csv-importer" ], "summary": "Download an uploaded CSV file", "operationId": "csv-download-source-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": "uploaded file ID", "name": "file_id", "in": "path", "required": true } ], "responses": { "200": { "description": "The uploaded CSV", "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 the stored file is no longer available", "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, 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, teams 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. Users and teams the import gave access to a project lose it again, unless their role on that project has changed since, in which case they are kept and warned. A project the import created is deleted together with what a template clone copies onto it and a project delete leaves behind: milestones on that project alone (one shared with another project is kept), its alert rules, its per-member rates and every team's access to it. Custom field definitions the import created and select options it added to an existing custom field are deleted, even when a value has been set on them since; such values are no longer shown. A deletion the plan or the role refuses leaves the field or option in place and warns with the count. Teams the import created are deleted and taken off every task in this workspace, and members it added to a team are removed again; a created team that has since gained other members or another workspace is kept, only this import's members are removed, and it is warned. This needs permission to manage the organization's users, as the import does; without it every team is left as it is, with a warning. Leads the import appointed among members who were already in a team keep the lead role. Imported users are not deleted in this version. 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, or another upload in this workspace is pending, mapping, ready, importing or reverting", "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/{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", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/organizations/{organization_id}/workspaces/{workspace_id}/work-preparation": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "work-preparation" ], "summary": "Get teammates who have not opened Focus and have no work waiting", "operationId": "get-work-preparation", "parameters": [ { "type": "integer", "description": "organization ID", "name": "organization_id", "in": "path", "required": true }, { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "minimum": 1, "type": "integer", "description": "Page number, 25 people per page", "name": "page", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.PageWithTotal-workpreparation_Candidate" } }, "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}/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}/forecast-availability": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Whether the workspace holds any work behind the reports' Scheduled and Draft forecast layers, so a client can default those overlays on only where they would show something. Covers the whole workspace and ignores the report period, so changing periods does not move the defaults.\nRequires 'view_reports'. Beyond that, both fields degrade to false rather than erroring when the caller lacks 'view_reports_forecasting' (Premium) or, for 'has_draft_work', 'view_draft_projects'.\nDeliberately ignores who is asking, the same way it ignores the period: a caller restricted to their own or their team's data can see a layer default on that draws nothing for them.", "produces": [ "application/json" ], "tags": [ "reports" ], "summary": "Check which forecast layers have data", "operationId": "get-forecast-availability", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true } ], "responses": { "200": { "description": "Forecast availability retrieved", "schema": { "$ref": "#/definitions/forecastavailability.Availability" } }, "403": { "description": "User is not authorized to access the workspace", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "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 server-computed forecast values for the future portion of the period, split by layer: scheduled work in live projects (sum_forecast_revenue, sum_forecast_labor_cost) and work in draft projects (sum_forecast_draft_revenue, sum_forecast_draft_labor_cost). The draft layer is empty for a requester without view_draft_projects. Supports four report types determined by the groupings field: no grouping = totals; single date grouping = trend; single project_id grouping = per-project; one or two non-date groupings = breakdown, which is forecast when a project_id level is present and the outer grouping is client, project, member or tag.\n'period' is optional in the shared dto.QueryRequest schema but required here: a request without one is rejected with a 400, unless the body is a shared-report marker ('shared_report_id' plus 'chart_key'), whose stored query supplies the period.", "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 the scheduled and draft forecast layers 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. Every field of the request body is optional on its own -- omitting `period` runs the query unbounded -- but the body must carry at least one selector (attributes, groupings or aggregations) or it is rejected with a 400 before reaching the engine. Other operations share this `dto.QueryRequest` body and add their own period rule; each states it in its own description.", "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; the timesheets dictionary additionally requires the query to project time_entry_id, user_account_id and start_utc, and is never returned on a shared read", "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.\n'period' is optional in the shared dto.QueryRequest schema but required here: it must resolve to concrete bounds, either as 'from' plus 'to' or as a 'preset', and a period that resolves to nothing is rejected with a 400. This endpoint does not accept shared-report marker bodies.\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 optional user_account_id, user_group_id (team), and user_tag_id (member tag) filters; the filters combine and resolve to members, and without any 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, user_group_id, and user_tag_id filters", "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.\n'period' is optional in the shared dto.QueryRequest schema but required here: it must resolve to concrete bounds, either as 'from' plus 'to' or as a 'preset', and a missing period or one that resolves to nothing is rejected with a 400. The exception is a shared-report marker body ('shared_report_id' plus 'chart_key'), whose stored query supplies the period.\nBreakdown reports (grouped by user_account_id) support optional pagination via 'page' and 'per_page', with a maximum per_page of 200.\nA breakdown may nest one 'client_id' or 'project_id' grouping under its member rows, with at most one time period grouping beside it; the grouping order is normalised to member, client/project, period.\nNested rows carry logged and billable duration and no capacity of their own. With a time period grouping, the period rows under a client or project repeat the member's 'sum_working_minutes' and 'is_time_off' for that period, which are properties of the member's day rather than of the client or project; they omit the baseline and elapsed sums, so the capacity share below is undefined on them.\nWithout a time period grouping, each nested row also carries the member's scheduled sums split by the task's project ('sum_scheduled_minutes', 'sum_scheduled_draft_minutes', 'sum_scheduled_remaining_minutes'; a client via its projects), and a project or client with scheduled work but no tracked time gets its own row. With a time period grouping the nested rows omit the scheduled sums, which stay on the member row along with its own per-period cells keyed by the period value.\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.\nA shared-report read ('shared_report_id' marker body, or a public link) omits 'sum_baseline_working_minutes' and 'sum_elapsed_working_minutes' entirely, and its users dictionary omits 'weekly_working_hours_is_default'.\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" } } } } }, "/shared/{token}": { "get": { "description": "No session. The token is the credential. Returns the viewer projection a grantee opens with -- the view's display metadata, the owner's allow-listed params, the shared period and the stored chart keys -- plus the window the charts are served on (a preset resolved now in the owner's calendar, so the reader is told the dates rather than resolving the preset themselves), plus who shared it, the workspace scope, display currency and utilization target (the owner's, or the default when the owner may not view it), and the dictionary the owner's stored filters resolve to, computed as the owner and redacted like every shared read. Every refusal -- an unknown, revoked or expired token, a retired share, a departed owner -- is the same undifferentiated 404.", "produces": [ "application/json" ], "tags": [ "PublicSharedReports" ], "summary": "Open a shared report by its public link", "operationId": "open-public-shared-report", "parameters": [ { "type": "string", "description": "Public link token", "name": "token", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/publicshare.OpenResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/shared/{token}/profitability": { "post": { "description": "No session. Runs the owner's stored profitability query for chart_key as the owner; see the query route for the contract.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "PublicSharedReports" ], "summary": "Run a profitability chart of a shared report by its public link", "operationId": "profitability-public-shared-report", "parameters": [ { "type": "string", "description": "Public link token", "name": "token", "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" }, { "description": "Which stored chart to run", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/publicshare.ChartRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/flexq.EnrichedResult" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "The owner may no longer view profitability reports", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/shared/{token}/query": { "post": { "description": "No session. Runs the owner's stored query for chart_key as the owner and returns the report exactly as the grantee routes do; everything else in the body is discarded. The view is charged to the owner's report-views quota. Every refusal of the link is the same undifferentiated 404; a chart the share does not store, or one asked for on a route that does not read its report type, is 404 shared_chart_not_found. This route reads summary and detailed reports, the workload route workload and utilization, the profitability route profitability.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "PublicSharedReports" ], "summary": "Run a chart of a shared report by its public link", "operationId": "query-public-shared-report", "parameters": [ { "type": "string", "description": "Public link token", "name": "token", "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" }, { "description": "Which stored chart to run", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/publicshare.ChartRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/flexq.EnrichedResult" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "The owner's report view quota is exceeded", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/shared/{token}/workload": { "post": { "description": "No session. Runs the owner's stored workload query for chart_key as the owner; see the query route for the contract.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "PublicSharedReports" ], "summary": "Run a workload chart of a shared report by its public link", "operationId": "workload-public-shared-report", "parameters": [ { "type": "string", "description": "Public link token", "name": "token", "in": "path", "required": true }, { "description": "Which stored chart to run", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/publicshare.ChartRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/flexq.EnrichedResult" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "The owner may no longer view workload reports", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "Not Found", "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 and time entries in bulk.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "composite" ], "summary": "Creates the main task, subtasks 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, caller role, and the caller's time and formatting context. 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.\nThe user block carries the timezone, current local and UTC time, and the user's time, date, and duration format preferences.\nIf present, the rules block carries the workspace's time-entry rules.", "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.WorkspaceContextREST" } }, "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}/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}/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" } }, "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}/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" } }, "402": { "description": "Timeline feature unavailable on the current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Timeline permission unavailable for the current role or module", "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" } }, "402": { "description": "Timeline feature unavailable on the current plan", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Timeline permission unavailable for the current role or module", "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, and requires the schedule_reports permission: 403 without it, 402 when the workspace's plan lacks report scheduling. 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. Because the call may create the share, it carries the state that share serves: charts is required (one entry per chart of the view type, each with its flexq_query) and period is the optional share period -- a preset or both from and to dates, anything else 400 invalid_shared_period -- both stored as sent. That state is written only when this call creates the share; a view that is already shared keeps the state it was shared with, so scheduling never republishes a report. 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, with the state a new share would serve", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/reportschedule.ViewSchedulePayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.ReportScheduleWithRecipients" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Payment Required", "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" } } } } }, "/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. Requires the share_reports permission: 403 without it, 402 when the workspace's plan lacks report sharing. Kept while the clients calling it move across; it will be removed once none are left. Sharing never touches the share's public link, and is never refused on account of one: a link serves whatever period the share stores, a preset rolling on every read. Re-sharing without `period` is not refused either: the link answers not-found from the next read until a later share stores a period again -- the public gate checks the period on every read. A re-share keeps the share's lock as it is; lock keys in the payload are ignored, since only the dates route writes the lock, and a share whose lock was never set is locked.", "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" } }, "402": { "description": "Payment Required", "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. The grantee list may be empty but not absent: an empty list creates or reuses the share and stores its state while granting nobody, which is how an owner publishes a public link without first sharing the view with anyone. 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 an active joined member or a pending invitee of the workspace; pending invitees receive a stored grant but cannot view the report until joined and are excluded from share notifications. 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 a preset or both from and to dates, stored as sent; anything else, a one-sided period included, is 400 invalid_shared_period, and when absent it is stored as absent. Everything else a recipient sees is read live off the view's own params. Requires the share_reports permission: 403 without it, 402 when the workspace's plan lacks report sharing. Sharing never touches the share's public link, and is never refused on account of one: a link serves whatever period the share stores, a preset rolling on every read. Re-sharing without `period` is not refused either: the link answers not-found from the next read until a later share stores a period again -- the public gate checks the period on every read. A re-share keeps the share's lock as it is; lock keys in the payload are ignored, since only the dates route writes the lock, and a share whose lock was never set is locked.", "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" } }, "402": { "description": "Payment Required", "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 default_private to all workspace members; permission settings are included only for workspace admins.", "produces": [ "application/json" ], "tags": [ "workspace-settings" ], "summary": "Get workspace 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 does not have access to workspace", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Updates permission settings and/or default_private atomically. Omitted fields are preserved; at least one is required and null is invalid. Requires workspace-admin rights. Private defaults require access_private_projects_tasks_feature.\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 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" } }, "402": { "description": "Private projects and tasks are not available on the current plan", "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, every grant standing on it -- including none, for a share whose grantees have all been revoked -- and the share's email schedule, null when it has none. 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. The schedule's recipients are as stored; a recipient the share no longer grants is still listed and is skipped at send time, so whether anyone would receive the email is decided against the grants beside it -- except the owner, who is always reachable without a grant, and whose self-grant this listing omits.", "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, scheduled, draft), 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" } } } }, "delete": { "description": "Owner-only. Retires the share with its grants, its public link and its schedule, in one transaction, and sharing the view again mints a fresh share with nothing carried over. Removing access is always the owner's to do, so no sharing permission is asked.", "tags": [ "SharedReports" ], "summary": "Unshare a saved view", "operationId": "unshare-shared-report", "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" }, "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}/dates": { "get": { "description": "Returns the window a read of the shared report runs on now, resolved in the owner's calendar: fixed dates as stored, a preset re-resolved on every read whether or not the share is locked. Also returns the period the owner shared and the lock, which decides only whether a reader may substitute their own period. Admitted by the same gate as the viewer read, and refused with the same undifferentiated 404. window is null for a share that stores no period; locked is sent either way.", "produces": [ "application/json" ], "tags": [ "SharedReports" ], "summary": "Get a shared report's dates", "operationId": "get-shared-report-dates", "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.DatesResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } } } }, "put": { "description": "Owner-only. The lock decides whether a reader may substitute their own period; the share's period decides the window served when they do not. Locking discards a reader's period on every read and changes nothing else: a preset keeps rolling, fixed dates stay fixed. Unlocking lets a reader choose their own dates, on a share that stores a period. A share whose lock was never set is locked. Neither is refused on account of the share's period or its public link -- a public reader can never substitute a period. Requires the share_reports permission. 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": "Lock or unlock a shared report's dates", "operationId": "set-shared-report-dates-lock", "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 lock", "name": "payload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/sharedreport.SetDatesLockPayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/sharedreport.DatesResponse" } }, "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" } } } } }, "/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 an active joined member or a pending invitee of the workspace; pending invitees receive a stored grant but cannot view the report until joined and are excluded from share notifications. 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. The caller needs the share_reports permission whatever the audience: a role without it is refused with 403, and a workspace whose plan lacks report sharing with 402 feature_not_available, both before the share is looked up. 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" } }, "402": { "description": "Payment Required", "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}/link": { "post": { "description": "Owner-only. Publishes the share to anyone holding the returned link -- the token is the credential, and a reader presenting it is served the report through the owner's eyes with no session at all. 201 with a fresh link when the share had none, 200 with the existing one otherwise; rotate replaces it. Requires the share_reports_externally permission (403 without it, 402 when the workspace's plan lacks external sharing) and a share that stores a period (400 period_required otherwise). Fixed dates are served as stored; a preset rolls, resolved in the owner's calendar on every read. Either way a public reader can never substitute a period of their own, whether or not the share is locked. An expiry in the past is refused (400 invalid_expires_at).", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SharedReports" ], "summary": "Mint a shared report's public link", "operationId": "mint-shared-report-link", "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": "Optional expiry", "name": "payload", "in": "body", "schema": { "$ref": "#/definitions/sharedreport.LinkPayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.SharedReportLink" } }, "201": { "description": "Created", "schema": { "$ref": "#/definitions/models.SharedReportLink" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Payment Required", "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" } } } }, "delete": { "description": "Owner-only. Retires the share's live link; the URL answers not-found from then on. The share and its grants are untouched. Taking access away is always the owner's to do, so no sharing permission is asked: a link stays revocable after the role or the plan that minted it is gone. 404 link_not_found when the share has no live link.", "tags": [ "SharedReports" ], "summary": "Revoke a shared report's public link", "operationId": "revoke-shared-report-link", "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" }, "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}/link/rotate": { "post": { "description": "Owner-only. Revokes the share's live link and mints a new one in its place, in one transaction, so a leaked URL stops working the moment the new one exists. Requires the share_reports_externally permission (403 without it, 402 when the workspace's plan lacks external sharing) and a share that stores a period, refused exactly as a first publish is (400 period_required). 404 link_not_found when the share has no live link to replace.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "SharedReports" ], "summary": "Rotate a shared report's public link", "operationId": "rotate-shared-report-link", "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": "Optional expiry", "name": "payload", "in": "body", "schema": { "$ref": "#/definitions/sharedreport.LinkPayload" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/models.SharedReportLink" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/response.Error" } }, "402": { "description": "Payment Required", "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" } } } } }, "/workspaces/{workspace_id}/shared-reports/{id}/schedule": { "put": { "description": "Owner-only, and requires the schedule_reports permission: 403 without it, 402 when the workspace's plan lacks report scheduling. 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" } }, "402": { "description": "Payment Required", "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" } } } }, "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 exactly, so names that differ only by case are different tags. 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" } }, "409": { "description": "Tags are required, and deleting the tags would leave time entries without tags (error=would_leave_time_entries_without_tags)", "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/merge": { "post": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Moves every attachment of the source tags onto the target — project, task and time-entry tags, goal tag filters and task board groups — then soft-deletes the sources. All-or-nothing, and not undoable: the source names stay restorable but the moved attachments are not separable again, and a source whose integration identity was adopted restores without it. Saved report views filtering on a merged-away tag are not rewritten and will match nothing until the user re-picks the surviving tag. The target must not be archived. Rejected up front when the source tags together are attached to too many items — merge fewer tags at once; the target's attachments never count against the limit. Fails with 409 when the target has no integration identity and more than one source carries one.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Merge tags", "operationId": "merge-tags", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "description": "Merge payload", "name": "mergePayload", "in": "body", "required": true, "schema": { "$ref": "#/definitions/tag.MergePayload" } } ], "responses": { "204": { "description": "Successfully merged tags" }, "400": { "description": "Invalid request, the target is among the sources, the target is archived, or the merge is too large", "schema": { "$ref": "#/definitions/response.Error" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/response.Error" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/response.Error" } }, "404": { "description": "One or more tags do not exist or are deleted", "schema": { "$ref": "#/definitions/response.Error" } }, "409": { "description": "The target has no integration identity and more than one source carries one", "schema": { "$ref": "#/definitions/response.Error" } }, "500": { "description": "Internal Server Error", "schema": { "$ref": "#/definitions/response.Error" } }, "503": { "description": "The merge did not finish inside its time budget and was rolled back; retry, ideally with fewer tags", "schema": { "$ref": "#/definitions/response.Error" } } } } }, "/workspaces/{workspace_id}/tags/time-entries/count": { "get": { "security": [ { "bearerAuth": [], "cookieAuth": [] } ], "description": "Counts the workspace's time entries, across every member, whose tags match: with match=only, every tag the entry has is one of ids. A time entry's tags are its own, or its task's when it has none of its own; deleted tags don't count. Counting stops past 1000 and reports has_more.", "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Count time entries by their tags", "operationId": "count-tag-time-entries", "parameters": [ { "type": "integer", "description": "workspace ID", "name": "workspace_id", "in": "path", "required": true }, { "type": "array", "items": { "type": "integer" }, "collectionFormat": "csv", "description": "tag IDs", "name": "ids", "in": "query", "required": true }, { "enum": [ "only" ], "type": "string", "description": "how an entry's tags relate to ids", "name": "match", "in": "query", "required": true } ], "responses": { "200": { "description": "Time entry count", "schema": { "$ref": "#/definitions/tag.TimeEntryCount" } }, "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}/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" } }, "409": { "description": "Tags are required, and deleting the tag would leave time entries without tags (error=would_leave_time_entries_without_tags)", "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) on the new entry, or on the running entry it would stop (error_values.time_entry_id names that entry)", "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.CurrentImportJobResponse": { "type": "object", "required": [ "job", "last_heartbeat_at", "stale" ], "properties": { "job": { "$ref": "#/definitions/backoffice.ImportJobView" }, "last_heartbeat_at": { "type": "string", "format": "date-time", "x-nullable": true }, "stale": { "description": "Stale indicates no recent persisted progress; it does not establish workflow failure.", "type": "boolean" } } }, "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.ImportAttemptView": { "type": "object", "required": [ "attempt_number", "created_at", "started_at", "state" ], "properties": { "attempt_number": { "type": "integer" }, "created_at": { "type": "string" }, "finished_at": { "type": "string" }, "heartbeat_at": { "type": "string" }, "origin": { "type": "string" }, "started_at": { "type": "string" }, "state": { "type": "string" }, "terminal_code": { "type": "string" }, "terminal_reason": { "type": "string" }, "updated_at": { "type": "string" } } }, "backoffice.ImportJobDetailView": { "type": "object", "required": [ "attempts", "created_at", "import_scope", "job_id", "progress", "source_product_id", "source_workspace_id", "status", "user_id" ], "properties": { "attempts": { "type": "array", "items": { "$ref": "#/definitions/backoffice.ImportAttemptView" } }, "created_at": { "type": "string" }, "finished_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" }, "source_workspace_id": { "type": "integer" }, "start_params": { "type": "object" }, "state": { "description": "State is the durable claim state; absent on legacy rows, which fall back to progress.", "type": "string" }, "status": { "type": "string" }, "terminal_code": { "type": "string" }, "terminal_reason": { "type": "string" }, "updated_at": { "type": "string" }, "user_id": { "type": "integer" } } }, "backoffice.ImportJobView": { "type": "object", "required": [ "created_at", "import_scope", "job_id", "progress", "source_product_id", "source_workspace_id", "status", "user_id" ], "properties": { "created_at": { "type": "string" }, "finished_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" }, "source_workspace_id": { "type": "integer" }, "state": { "description": "State is the durable claim state; absent on legacy rows, which fall back to progress.", "type": "string" }, "status": { "type": "string" }, "terminal_code": { "type": "string" }, "terminal_reason": { "type": "string" }, "updated_at": { "type": "string" }, "user_id": { "type": "integer" } } }, "backoffice.StartWorkspaceImportResponse": { "type": "object", "required": [ "already_running", "job", "owner_user_id" ], "properties": { "already_running": { "description": "AlreadyRunning is true when the importer returned the workspace's existing active import\ninstead of starting a new one.", "type": "boolean" }, "job": { "$ref": "#/definitions/backoffice.ImportJobView" }, "owner_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", "tag_present", "task_present" ], "properties": { "description_present": { "type": "boolean" }, "enabled": { "type": "boolean" }, "project_present": { "type": "boolean" }, "tag_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.startWorkspaceImportPayload": { "type": "object", "required": [ "reason", "source_workspace_id" ], "properties": { "active_only": { "type": "boolean", "example": true }, "reason": { "type": "string", "maxLength": 1000 }, "source_workspace_id": { "type": "integer", "minimum": 1, "example": 623123 }, "time_entries_end": { "type": "string", "example": "2026-04-14" }, "time_entries_start": { "type": "string", "example": "2026-03-31" } } }, "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": { "billable": { "type": "boolean", "x-nullable": true }, "project_id": { "type": "integer" }, "tag_ids": { "description": "TagIDs and Billable are what the rule stamps onto the entry it matches.\nBoth are pointer/nullable so \"omitted\" stays distinguishable from \"set to\nnothing\" -- a null (or absent) tag_ids leaves the entry's tags inherited,\nwhile [] is an explicit instruction to clear them.\n\nNo max on tag_ids, matching every sibling tag_ids payload (time entry,\ntask, project). A cap here would also be decorative rather than enforced,\nbecause these two handlers never call h.validator.Validate -- a validate\ntag on this struct does nothing but put an untrue constraint in the API\ndocs. The real bound is that every id must resolve to a live workspace tag.", "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "task_id": { "type": "integer" }, "title": { "type": "string" } } }, "calendar.pushTargetRequest": { "type": "object", "required": [ "calendar_id", "integration_id" ], "properties": { "calendar_id": { "type": "integer" }, "integration_id": { "type": "integer" } } }, "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": { "description": "Send together with start_date; must be on or after start_date.", "type": "string", "format": "date" }, "estimate_type": { "type": "string", "enum": [ "daily", "total" ] }, "estimated_mins": { "type": "integer", "minimum": 0 }, "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": { "description": "Send together with end_date; a date without the other is rejected.", "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_entry": { "$ref": "#/definitions/composite.TimeEntryPayload" } } }, "composite.CreateTasksResponse": { "type": "object", "required": [ "estimate_allocations", "subtasks", "task", "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_entry": { "$ref": "#/definitions/models.TimeEntry" } } }, "composite.TimeEntryPayload": { "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 }, "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. A blank or unmapped\ntask creates a taskless time entry; a non-empty task reference that cannot\nbe matched still stops the row. Time entries whose task and user are matched\nare 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 and teams are added — never\nremoved — and description, notes, estimated_minutes, start_date, end_date,\nbillable, priority, status and recurring are each written when the row\ncarries a value and left alone when the cell is blank or the column\nunmapped. 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 —\npermission or plan denied, 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.FileSummaryResponse": { "type": "object", "required": [ "file_id", "file_name" ], "properties": { "file_id": { "type": "integer" }, "file_name": { "type": "string" } } }, "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": { "description": { "type": "string" }, "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.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\". Treat nil as unknown rather 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;\ntreat that as unknown, not as \"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.UploadRequestSummaryResponse": { "type": "object", "required": [ "created_at", "dry_run_status", "files", "id", "progress", "send_invites", "stats", "status", "updated_at", "user_id", "warnings", "workspace_id" ], "properties": { "created_at": { "type": "string" }, "dry_run_status": { "type": "string" }, "files": { "type": "array", "items": { "$ref": "#/definitions/csv.FileSummaryResponse" } }, "id": { "type": "integer" }, "import_job_id": { "type": "string" }, "progress": { "type": "integer" }, "send_invites": { "type": "boolean" }, "stats": { "$ref": "#/definitions/csv.EntityCounts" }, "status": { "type": "string" }, "updated_at": { "type": "string" }, "user_id": { "type": "integer" }, "warnings": { "type": "array", "items": { "type": "string" } }, "workspace_id": { "type": "integer" } } }, "csv.UploadResponse": { "type": "object", "required": [ "available_targets", "can_invite_members", "files", "id", "unsettable_fields", "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.AllowedUsersPayload": { "type": "object", "required": [ "user_ids" ], "properties": { "user_ids": { "type": "array", "maxItems": 5000, "uniqueItems": true, "items": { "type": "integer" } } } }, "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" ] }, "max_selected_users": { "type": "integer", "maximum": 100, "minimum": 1, "x-nullable": true }, "name": { "type": "string" }, "options": { "type": "array", "maxItems": 100, "items": { "$ref": "#/definitions/customfield.CreateOptionPayload" } } } }, "customfield.ReorderOptionsPayload": { "type": "object", "required": [ "ordered_ids" ], "properties": { "ordered_ids": { "description": "The options to reorder. An active option left out keeps its position\nrelative to the others.", "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": "Every active custom field of this entity type, in the order to apply.", "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" }, "max_selected_users": { "description": "Null clears the limit; omit the field to keep it.", "type": "integer", "maximum": 100, "minimum": 1, "x-nullable": true }, "name": { "type": "string" } } }, "customfield.Values": { "type": "object", "additionalProperties": {} }, "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_slots_per_task", "max_time_entries_per_task", "min_slots_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_slots_per_task": { "type": "integer" }, "max_time_entries_per_task": { "type": "integer" }, "min_slots_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\nplan feature and permissions; without them the stage fails with the\ncustom field 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" } } }, "designation.CreateDesignationPayload": { "type": "object", "required": [ "name" ], "properties": { "member_ids": { "type": "array", "maxItems": 100, "uniqueItems": true, "items": { "type": "integer" } }, "name": { "type": "string" } } }, "designation.CreateDesignationsRequest": { "type": "object", "required": [ "designations" ], "properties": { "designations": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "$ref": "#/definitions/designation.CreateDesignationPayload" } } } }, "designation.Member": { "type": "object", "required": [ "created_at", "designation_id", "toggl_user_id", "updated_at", "workspace_id" ], "properties": { "created_at": { "type": "string" }, "designation_id": { "type": "integer" }, "toggl_user_id": { "type": "integer" }, "updated_at": { "type": "string" }, "workspace_id": { "type": "integer" } } }, "designation.MemberPayload": { "type": "object", "required": [ "designation_id", "toggl_user_id" ], "properties": { "designation_id": { "type": "integer" }, "toggl_user_id": { "type": "integer" } } }, "designation.UpdateDesignationPayload": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "designation.UpdateDesignationRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "designation.UpdateDesignationsRequest": { "type": "object", "required": [ "designations" ], "properties": { "all_or_none": { "type": "boolean" }, "designations": { "type": "array", "maxItems": 100, "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/definitions/designation.UpdateDesignationPayload" } } } }, "designation.UpdateMembersRequest": { "type": "object", "properties": { "add": { "type": "array", "maxItems": 100, "items": { "$ref": "#/definitions/designation.MemberPayload" } }, "remove": { "type": "array", "maxItems": 100, "items": { "$ref": "#/definitions/designation.MemberPayload" } } } }, "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" }, "timesheets": { "$ref": "#/definitions/dictionary.TimesheetDictionary" }, "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" ], "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" } } }, "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" }, "member_estimates": { "type": "array", "items": { "$ref": "#/definitions/dictionary.TaskMemberEstimate" } }, "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.TaskMemberEstimate": { "type": "object", "required": [ "estimated_mins", "user_account_id" ], "properties": { "estimated_mins": { "type": "integer" }, "user_account_id": { "type": "integer" } } }, "dictionary.TimesheetDict": { "type": "object", "required": [ "end_date", "id", "start_date", "status", "user_account_id" ], "properties": { "end_date": { "type": "string", "format": "date" }, "id": { "description": "Zero for a period with no row yet, so not an identifier to key on.", "type": "integer" }, "reviewed_at": { "type": "string", "format": "date-time" }, "start_date": { "type": "string", "format": "date" }, "status": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "user_account_id": { "type": "integer" } } }, "dictionary.TimesheetDictionary": { "type": "object", "additionalProperties": { "$ref": "#/definitions/dictionary.TimesheetDict" } }, "dictionary.UserDict": { "type": "object", "required": [ "email", "id", "name" ], "properties": { "custom_field_values": { "type": "array", "items": { "$ref": "#/definitions/models.CustomFieldValue" } }, "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", "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", "properties": { "conditions": { "type": "array", "items": { "$ref": "#/definitions/dto.FilterRequest" } }, "operator": { "type": "string" }, "property": { "type": "string" }, "value": {} } }, "dto.GroupingRequest": { "type": "object", "required": [ "property" ], "properties": { "property": { "type": "string" }, "show_empty": { "type": "boolean" } } }, "dto.ModifiersRequest": { "type": "object", "additionalProperties": {} }, "dto.OrdinationRequest": { "type": "object", "required": [ "property" ], "properties": { "direction": { "type": "string" }, "nulls": { "type": "string" }, "property": { "type": "string" } } }, "dto.PaginationRequest": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "dto.PeriodRequest": { "type": "object", "properties": { "from": { "type": "string" }, "preset": { "type": "string" }, "to": { "type": "string" } } }, "dto.QueryRequest": { "type": "object", "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": { "description": "Paginated row-level queries are also sorted by start_utc and time_entry_id in the first ordination's\ndirection, then by selected per-value attributes such as tag_id, so tied rows keep the same order on every page.", "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, pagination — is discarded.\nPeriod is the one exception: on an unlocked share that stores a period (a preset or\nfixed dates) it is the window served, still as the owner. A locked share, and a share\nthat stores no period, discard it. Absent, the request is served by value exactly as it\nalways 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": {} } } }, "emailunsubscribe.Response": { "type": "object", "required": [ "enabled", "kind" ], "properties": { "enabled": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "daily_brief", "timer_still_running" ] } } }, "events.PlatformOrigin": { "type": "string", "enum": [ "web", "mobile", "desktop", "extension", "mcp", "cli" ], "x-enum-varnames": [ "PlatformOriginWeb", "PlatformOriginMobile", "PlatformOriginDesktop", "PlatformOriginBrowserExtension", "PlatformOriginMCP", "PlatformOriginCLI" ] }, "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" }, "overlay": { "description": "Optional, and absent on every build that predates overlays. See\nmodels.ExtensionIntegration.Overlay for why both are stored.", "type": "object" } } }, "extensionintegration.UpsertPayload": { "type": "object", "required": [ "definition", "name" ], "properties": { "definition": { "type": "object" }, "name": { "type": "string" }, "overlay": { "type": "object" } } }, "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" }, "use_project": { "type": "boolean" }, "use_tags": { "type": "boolean" }, "use_task": { "description": "Use* are deliberately optional, unlike the required create flags. Every\nextension build that predates them sends only the create triple, so an\nomitted key means \"leave whatever governs this integration\": unchanged\nwhen the row exists, and for a new row whatever the organization's\n`__default__` says, falling back to permissive when it has none\neither. Reading omission as `true` instead would let an old client\nlift a restriction it does not know exists, simply by saving the\ncreation setting — including by creating a fresh specific row that\noutranks a restrictive default.", "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_ambiguous": { "description": "ProjectAmbiguous reports that the workspace holds more than one live\nproject with the supplied name, so none was attached.\n\nNeither existing field can carry this. `project_resolved: false`\nmeans the name matched nothing, and a client showing \"couldn't find\nthat project\" would send the user to create a project that already\nexists — twice over. `project_dropped` is a policy refusal, which is\nthe organization's choice rather than something the user can fix.\nHere the fix is specific and worth saying: the names collide, pick\nthe project by hand or rename one.", "type": "boolean" }, "project_created": { "type": "boolean" }, "project_dropped": { "description": "ProjectDropped reports that the payload named a project the\norganization's policy forbids the extension from using, so it was\nnever resolved and never narrowed matching.\n\n`project_resolved` cannot carry this: nil there already means \"no name\nwas supplied\", which is the opposite situation — a client showing\n\"couldn't find that project\" for a policy decision would send the user\nto fix a project that is fine.", "type": "boolean" }, "project_inaccessible": { "description": "ProjectInaccessible reports that a project with the supplied name\nexists but this caller may not use it, so none was attached and none\nwas created even with `create_project_if_not_found` on.\n\nWithout this the response would be `project_resolved: false,\nproject_created: false`, indistinguishable from \"the name matched\nnothing\", and the user would retry into the same dead end every\ntime. The fix is on their side of the fence: ask an admin for access\nor pick the project by hand.\n\nSet only on the create-task path, the one place a project is ever\ncreated: `create_project_if_not_found` is inert on every taskless\npath, so a start that goes taskless never creates a project for any\nunresolved name and never reports this either.", "type": "boolean" }, "project_resolved": { "type": "boolean" }, "resolution_strategy": { "type": "string" }, "tags_created": { "type": "array", "items": { "type": "string" } }, "tags_dropped": { "description": "TagsDropped reports that the tags resolved but did not land on the\nentry, which started without them.\n\nTHREE causes, one report, because the client's job is the same in all\nof them: the write refused the override and it was retried untagged,\nthe path deliberately did not attempt it (`taskless_unauthorized`,\nwhere the caller was just denied the task those tags were for), or the\norganization's policy forbids the extension using tags at all so they\nwere never resolved.\n\nDistinct from TagsNotFound, which means the names never resolved: a\nclient that conflated the two would send the user looking for a tag\nthat exists. A bool rather than the names because the client sent\nthem — what it cannot otherwise know is whether they survived. Under\nthe policy case BOTH tag lists come back empty, which is exactly what\na fully successful start looks like.\n\nAlways sent (no `omitempty`) but declared optional: a client talking\nto a server that predates this field gets nothing, so typing it as\nrequired — which `--requiredByDefault` does — would lie to every\nclient until this ships.", "type": "boolean" }, "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" } } }, "forecastavailability.Availability": { "type": "object", "required": [ "has_draft_work", "has_scheduled_work", "workspace_id" ], "properties": { "has_draft_work": { "type": "boolean" }, "has_scheduled_work": { "type": "boolean" }, "workspace_id": { "type": "integer" } } }, "goal.CreatePayload": { "type": "object", "required": [ "comparison", "recurrence", "start_date", "target_seconds" ], "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.PreviewPayload": { "type": "object", "required": [ "recurrence", "start_date" ], "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" }, "billable": { "type": "boolean", "x-nullable": true }, "client_ids": { "type": "array", "items": { "type": "integer" } }, "comparison": { "type": "string" }, "description": { "type": "string", "x-nullable": true }, "end_date": { "type": "string", "format": "date", "x-nullable": true }, "icon": { "type": "string" }, "monthly_anchor": { "type": "string", "enum": [ "calendar", "first_workday" ], "x-nullable": true }, "name": { "type": "string" }, "project_ids": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "description": "Period-grid fields. Changing any of these restarts the goal's streak bookkeeping\n(previous_streak, best_streak, periods_met, and last_notified_at reset).", "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" } } } }, "importer.ImportDataDeletion": { "type": "object", "required": [ "finished_at", "requested_at", "requested_by", "status", "summary" ], "properties": { "finished_at": { "type": "string", "x-nullable": true }, "requested_at": { "type": "string" }, "requested_by": { "type": "integer" }, "status": { "type": "string", "enum": [ "deleting", "deleted", "failed" ] }, "summary": { "allOf": [ { "$ref": "#/definitions/importer.ImportDataDeletionSummary" } ], "x-nullable": true } } }, "importer.ImportDataDeletionCounts": { "type": "object", "required": [ "deleted", "skipped" ], "properties": { "deleted": { "type": "integer" }, "skipped": { "type": "integer" } } }, "importer.ImportDataDeletionSummary": { "type": "object", "required": [ "clients", "projects", "saved_views", "tags", "tasks", "time_entries" ], "properties": { "alerts": { "$ref": "#/definitions/importer.ImportDataDeletionCounts" }, "clients": { "$ref": "#/definitions/importer.ImportDataDeletionCounts" }, "projects": { "$ref": "#/definitions/importer.ImportDataDeletionCounts" }, "saved_views": { "$ref": "#/definitions/importer.ImportDataDeletionCounts" }, "tags": { "$ref": "#/definitions/importer.ImportDataDeletionCounts" }, "tasks": { "$ref": "#/definitions/importer.ImportDataDeletionCounts" }, "time_entries": { "$ref": "#/definitions/importer.ImportDataDeletionCounts" } } }, "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", "data_deletion", "import_scope", "job_id", "progress", "retry", "source_product_id", "source_workspace_id", "updated_at", "user_id", "workspace_id" ], "properties": { "created_at": { "type": "string" }, "data_deletion": { "allOf": [ { "$ref": "#/definitions/importer.ImportDataDeletion" } ], "x-nullable": true }, "failed_activities": { "description": "FailedActivities lists the entity types whose importer activities failed. Recorded when the\njob fails; older failed jobs may carry a hint read from the workflow history instead.", "type": "array", "items": { "type": "string" } }, "finished_at": { "type": "string" }, "import_scope": { "type": "string" }, "job_id": { "type": "string" }, "last_activity_at": { "description": "LastActivityAt is when the importer last reported progress. A long stage can run without\nreporting, so an old value alone does not mean the import stopped.", "type": "string" }, "options": { "$ref": "#/definitions/importer.ImportJobOptions" }, "progress": { "type": "integer" }, "progress_details": { "$ref": "#/definitions/importer.ImportProgressDetails" }, "result_summary": { "$ref": "#/definitions/importer.ImportResultSummary" }, "retry": { "$ref": "#/definitions/importer.ImportJobRetry" }, "source_product_id": { "type": "integer" }, "source_workspace_id": { "type": "integer" }, "source_workspace_name": { "type": "string" }, "started_by_support": { "description": "StartedBySupport is present only when the recorded import origin is Backoffice.", "type": "boolean" }, "status": { "type": "string" }, "updated_at": { "type": "string" }, "user_id": { "type": "integer" }, "workspace_id": { "type": "integer" } } }, "importer.ImportJobOptions": { "type": "object", "required": [ "active_only", "import_scope", "skip_user_import" ], "properties": { "active_only": { "type": "boolean" }, "import_scope": { "type": "string", "enum": [ "full_workspace", "user_only" ] }, "skip_user_import": { "type": "boolean" }, "time_entries_end": { "type": "string", "format": "date" }, "time_entries_start": { "type": "string", "format": "date" } } }, "importer.ImportJobResponse": { "type": "object", "required": [ "created_at", "data_deletion", "import_scope", "job_id", "progress", "retry", "source_product_id", "source_workspace_id", "status" ], "properties": { "active_only": { "type": "boolean" }, "created_at": { "type": "string" }, "data_deletion": { "allOf": [ { "$ref": "#/definitions/importer.ImportDataDeletion" } ], "x-nullable": true }, "failed_activities": { "description": "FailedActivities lists the entity types whose importer activities failed, as recorded when\nthe job failed. Absent when none failed or the job predates the record.", "type": "array", "items": { "type": "string" } }, "finished_at": { "type": "string" }, "import_scope": { "type": "string" }, "job_id": { "type": "string" }, "last_activity_at": { "description": "LastActivityAt is when the importer last reported progress. A long stage can run without\nreporting, so an old value alone does not mean the import stopped.", "type": "string" }, "options": { "$ref": "#/definitions/importer.ImportJobOptions" }, "progress": { "type": "integer" }, "progress_details": { "$ref": "#/definitions/importer.ImportProgressDetails" }, "result_summary": { "$ref": "#/definitions/importer.ImportResultSummary" }, "retry": { "$ref": "#/definitions/importer.ImportJobRetry" }, "scope_limited": { "description": "ScopeLimited reports whether a Track import left data behind: archived\nclients, projects and tasks skipped by active_only, or time entries\noutside a requested range. Always false for non-Track imports, which\nignore both. It does not reflect import_scope: a user_only import is\npermission-capped, not narrowed by request. Absent for jobs that\npredate the requested-params columns.", "type": "boolean" }, "source_product_id": { "type": "integer" }, "source_workspace_id": { "type": "integer" }, "source_workspace_name": { "type": "string" }, "started_by_support": { "description": "StartedBySupport is present only when the recorded import origin is Backoffice.", "type": "boolean" }, "status": { "type": "string" }, "time_entries_end": { "type": "string", "format": "date" }, "time_entries_start": { "type": "string", "format": "date" }, "time_range_limited": { "type": "boolean" }, "updated_at": { "type": "string" } } }, "importer.ImportJobRetry": { "type": "object", "required": [ "eligible", "reason", "recovery_action" ], "properties": { "eligible": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "in_progress", "completed", "data_deleted", "not_resumable", "restart_required", "failed_terminal", "attempt_limit_reached", "retry_unavailable" ], "x-nullable": true }, "recovery_action": { "type": "string", "enum": [ "none", "wait", "retry", "start_new_import" ] } } }, "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", "enum": [ "fetch", "teams", "members", "clients", "projects", "tasks", "tags", "time_entries" ] }, "index": { "type": "integer" }, "started_at": { "description": "StartedAt is when the job entered this stage. Set on the current stage only, and absent when\nthe stage started before it was recorded.", "type": "string" }, "status": { "type": "string", "enum": [ "pending", "active", "completed", "failed", "skipped" ] }, "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" }, "saved_reports": { "type": "integer" }, "tasks": { "type": "integer" }, "time_entries": { "type": "integer" }, "timesheet_setups": { "type": "integer" }, "timesheets": { "type": "integer" }, "warning_details": { "description": "WarningDetails groups every warning of the run by code and entity, without the cap Warnings\nhas. Absent for summaries written before it was recorded.", "type": "array", "items": { "$ref": "#/definitions/importer.ImportResultWarning" } }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "importer.ImportResultWarning": { "type": "object", "required": [ "code", "count", "entity", "message" ], "properties": { "code": { "type": "string", "example": "project_import_conflict" }, "count": { "type": "integer", "example": 3 }, "entity": { "type": "string", "enum": [ "member", "client", "project", "task", "time_entry", "tag", "alert", "reminder", "working_hours", "timesheet_setup", "timesheet", "rate", "saved_report" ], "example": "time_entry" }, "message": { "type": "string", "example": "Some records were not imported because their project could not be imported." } } }, "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", "rate_effect", "seat_effect", "summary" ], "properties": { "mappings": { "type": "array", "items": { "$ref": "#/definitions/importer.importPreviewMapping" } }, "member_sections": { "$ref": "#/definitions/importer.importPreviewMemberSections" }, "members": { "type": "array", "items": { "$ref": "#/definitions/importer.member" } }, "rate_effect": { "$ref": "#/definitions/importer.importPreviewRateEffect" }, "seat_effect": { "$ref": "#/definitions/importer.importPreviewSeatEffect" }, "summary": { "$ref": "#/definitions/importer.importPreviewSummary" }, "warnings": { "type": "array", "items": { "$ref": "#/definitions/importer.importPreviewWarning" } } } }, "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.importPreviewRateEffect": { "type": "object", "required": [ "imports_rates", "levels", "rate_types", "reason", "replaces_existing_rates", "skipped_levels" ], "properties": { "imports_rates": { "type": "boolean" }, "levels": { "type": "array", "items": { "type": "string", "enum": [ "workspace", "workspace_user", "project", "project_user" ] } }, "rate_types": { "type": "array", "items": { "type": "string", "enum": [ "billable", "labor" ] } }, "reason": { "description": "Reason tells why no rates are imported. Null when rates are imported.", "type": "string", "enum": [ "personal_import", "source_has_no_rates" ], "x-nullable": true }, "replaces_existing_rates": { "description": "ReplacesExistingRates reports that each imported rate replaces the rate history this\nworkspace has for the same workspace, member or project.", "type": "boolean" }, "skipped_levels": { "description": "SkippedLevels lists source rate levels that are never imported.", "type": "array", "items": { "type": "string", "enum": [ "task" ] } } } }, "importer.importPreviewSeatEffect": { "type": "object", "required": [ "members_added", "new_seats" ], "properties": { "members_added": { "description": "MembersAdded counts the people the import adds to this workspace.", "type": "integer" }, "new_seats": { "description": "NewSeats counts the added people who have no Toggl Focus access in the organization yet, so\neach takes a new seat. Null when the organization's members could not be read.", "type": "integer", "x-nullable": true } } }, "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": [ "billable", "created_at", "id", "project_id", "tag_ids", "task_id", "title", "updated_at" ], "properties": { "billable": { "description": "Billable is the billable flag the rule forces on the entry. NULL (nil) means\nthe rule says nothing and billable stays inherited from the task/project. A\nnon-nil value lands on the entry as a manual billable source, so the\nworkspace \"disallow billable override\" policy coerces it back to inherited\nthe same way it coerces a client-sent manual flag.", "type": "boolean", "x-nullable": true }, "created_at": { "type": "string" }, "id": { "type": "integer" }, "project_id": { "type": "integer", "x-nullable": true }, "tag_ids": { "description": "TagIDs is the tag set the rule stamps onto the entry it categorizes. NULL\n(nil) means the rule says nothing about tags and the entry keeps inheriting\nfrom its task. A non-nil value — including an empty array — replaces the\nentry's tags outright, exactly as picking tags on the entry itself does.", "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "task_id": { "type": "integer", "x-nullable": true }, "title": { "type": "string" }, "updated_at": { "type": "string" } } }, "mcp.UserContext": { "type": "object", "required": [ "current_local_time", "current_utc_time", "date_format", "duration_format", "time_format", "timezone", "week_starts_on" ], "properties": { "current_local_time": { "type": "string" }, "current_utc_time": { "type": "string" }, "date_format": { "type": "string" }, "duration_format": { "type": "string" }, "time_format": { "type": "string" }, "timezone": { "type": "string" }, "week_starts_on": { "type": "string" } } }, "mcp.WorkspaceContextREST": { "type": "object", "required": [ "organization_id", "user", "workspace_id" ], "properties": { "organization_id": { "type": "integer" }, "role": { "type": "string" }, "rules": { "$ref": "#/definitions/mcp.WorkspaceRules" }, "user": { "$ref": "#/definitions/mcp.UserContext" }, "workspace_id": { "type": "integer" } } }, "mcp.WorkspaceRules": { "type": "object", "required": [ "disallow_billable_override", "required_fields" ], "properties": { "disallow_billable_override": { "type": "boolean" }, "required_fields": { "type": "array", "items": { "type": "string" } } } }, "milestone.PartialUpdatePayload": { "type": "object", "properties": { "color": { "description": "nolint:lll", "type": "string" }, "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", "minLength": 1 }, "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_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_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.CustomFieldAllowedUsers": { "type": "object", "required": [ "user_ids" ], "properties": { "user_ids": { "type": "array", "items": { "type": "integer" } } } }, "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" }, "max_selected_users": { "description": "MaxSelectedUsers caps a users field's value; nil means unlimited.", "type": "integer", "x-nullable": true }, "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" }, "toggl_user_id": { "description": "The task creator. Virtual entries carry the template task's creator.", "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" }, "overlay": { "description": "Overlay is the delta this row stores against a shipped integration, when\nit customises one rather than defining its own. Definition still holds the\ncomplete document: builds that predate overlays read that and are\nunaffected, newer ones prefer this and merge it onto the base they ship,\nwhich is what lets a later fix to that base reach the organization.\n\nThe backend never merges the two — built-in definitions live only in the\nextension bundle, so there is no base here to merge onto.", "type": "object" }, "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", "use_project", "use_tags", "use_task" ], "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" }, "use_project": { "type": "boolean" }, "use_tags": { "type": "boolean" }, "use_task": { "description": "Use* gate whether the extension may attach the entity at all, separate\nfrom whether it may create a missing one. An entity that already exists\nis attached before any Create* flag is read, so these stop the extension\nSUPPLYING one rather than \"stop inventing them\".\n\nWhat the extension supplies, not what the entry holds: with UseProject\nfalse a start behaves as it would on a page that maps no project, and a\ntask it matches still carries that task's own project.\n\nPointers only so a write can say \"leave this alone\": the columns are NOT\nNULL, so a row read back always has all three. An omitted key on upsert\nkeeps whatever already governs the integration — the stored value when the\nrow exists, and the organization's `__default__` when it does not (falling\nback to permissive when there is no default either). Never a plain `true`:\nthe shipped extension still sends only the create triple and must not be\nable to lift a restriction it does not know exists, including by minting a\nfresh specific row that would outrank a restrictive default.", "type": "boolean" } } }, "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 from StartDate at creation and re-snapshotted\non a PATCH that changes the period grid (recurrence/monthly_anchor/start_date --\ntoggl/ic-tribe#2142). Unlike the user's own settings.StartWeekOn (db column\nstart_week_on on user_settings -- note the transposed name), it never shifts merely\nbecause that setting changed later, so toggling it cannot desync the warehouse\nmaterialization from the streak anchor (toggl/ic-tribe#1887). NULL for non-weekly goals\n(including a goal moved away from weekly) and for weekly goals created before this\ncolumn 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", "deselected_calendar_ids", "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" }, "deselected_calendar_ids": { "description": "IDs of this integration's switched-off calendars; Calendars lists only the selected ones.", "type": "array", "items": { "type": "integer" } }, "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.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-models_Trait": { "type": "object", "required": [ "data", "page", "per_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.Trait" } }, "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-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_UploadRequestSummaryResponse": { "type": "object", "required": [ "data", "page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/csv.UploadRequestSummaryResponse" } }, "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.PageWithTotal-workpreparation_Candidate": { "type": "object", "required": [ "data", "page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/workpreparation.Candidate" } }, "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", "estimate_source", "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" }, "estimate_source": { "enum": [ "manual", "tasks" ], "allOf": [ { "$ref": "#/definitions/models.ProjectEstimateSource" } ] }, "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.ProjectEstimateSource": { "type": "string", "enum": [ "manual", "tasks" ], "x-enum-varnames": [ "ProjectEstimateSourceManual", "ProjectEstimateSourceTasks" ] }, "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" }, "billable": { "type": "boolean" }, "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", "estimate_source", "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" }, "estimate_source": { "enum": [ "manual", "tasks" ], "allOf": [ { "$ref": "#/definitions/models.ProjectEstimateSource" } ] }, "estimated_mins": { "type": "integer" }, "filtered_task_count": { "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" } }, "picker_parent_group_count": { "type": "integer" }, "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.SharedReportLink": { "type": "object", "required": [ "created_at", "created_by", "id", "shared_report_id", "token" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "integer" }, "deleted_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "id": { "type": "integer" }, "shared_report_id": { "type": "integer" }, "token": { "type": "string" }, "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": { "$ref": "#/definitions/models.StreamEventAction" }, "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.StreamEventAction": { "type": "string", "enum": [ "insert", "delete", "update" ], "x-enum-varnames": [ "StreamEventActionCreated", "StreamEventActionDeleted", "StreamEventActionUpdated" ] }, "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", "scheduled_quantity", "subscription_item_id", "updated_at" ], "properties": { "discount": { "$ref": "#/definitions/models.SubscriptionItemDiscountInfo" }, "quantity": { "description": "Quantity is the live paid quantity (number of paid licenses).", "type": "integer" }, "scheduled_quantity": { "description": "ScheduledQuantity is the scheduled next-cycle quantity when a change is pending\nin Stripe (typically a decrease); nil when there is no pending change — no\nschedule, or the scheduled quantity equals the live 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", "x-nullable": true }, "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_recurring_series": { "description": "IsRecurringSeries marks a canonical series root (S). Server-owned and\nread-only: no current API path can set it, and the response only exposes\nthe marker while series behavior stays disabled.", "type": "boolean" }, "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_rule": { "description": "The rule of the task's series (RRULE with DTSTART); omitted for a normal task and once the series has stopped.", "type": "string" }, "recurring_series_id": { "description": "The series this task is an occurrence of; omitted for a normal task. Only the server sets it.", "type": "integer" }, "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.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": { "description": "Whether `billable` was set on the entry (`manual`) or resolved from its task, else its project (`task_default`).", "enum": [ "manual", "task_default" ], "allOf": [ { "$ref": "#/definitions/models.BillableSource" } ] }, "calendar_event_id": { "type": "integer" }, "calendar_id": { "description": "CalendarID is the calendar service's calendar PK. It stays set after a calendar deselect clears calendar_event_id.", "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "duration": { "description": "Tracked duration in seconds; omitted while the timer is running and for an entry that is only planned.", "type": "integer" }, "id": { "type": "integer" }, "pattern_generated": { "description": "PatternGenerated is the response-facing derivative of GeneratedByTaskID:\ntrue when the entry was materialized by a series pattern.", "type": "boolean" }, "pattern_managed": { "description": "PatternManaged reports that the pattern engine owns this entry. Server-owned;\npresent in responses, never bindable from a payload.", "type": "boolean" }, "planned_at": { "type": "string", "format": "date-time" }, "planned_duration": { "description": "Planned duration in seconds.", "type": "integer" }, "planned_start": { "description": "Planned start, for time planned on the calendar.", "type": "string", "format": "date-time" }, "project_id": { "type": "integer" }, "start": { "description": "Start of the tracked time; omitted for an entry that is only planned.", "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.TimeEntryGroup": { "type": "object", "required": [ "id", "time_entries", "type" ], "properties": { "id": { "type": "integer" }, "time_entries": { "type": "array", "items": { "$ref": "#/definitions/models.TimeEntryGroupEntry" } }, "type": { "type": "string", "enum": [ "users" ] } } }, "models.TimeEntryGroupEntry": { "type": "object", "required": [ "calendar_event_id", "id", "planned_start" ], "properties": { "calendar_event_id": { "type": "integer" }, "calendar_provider": { "type": "string", "enum": [ "google", "outlook" ] }, "description": { "type": "string" }, "duration": { "type": "integer" }, "event": { "$ref": "#/definitions/models.TimeEntryGroupEntryEvent" }, "id": { "type": "integer" }, "planned_duration": { "type": "integer" }, "planned_start": { "type": "string", "format": "date-time" }, "project": { "$ref": "#/definitions/models.TimeEntryGroupEntryProject" }, "start": { "description": "Start and Duration are set once the entry has tracked time.", "type": "string", "format": "date-time" }, "task": { "$ref": "#/definitions/models.TimeEntryGroupEntryTask" }, "timezone": { "type": "string" } } }, "models.TimeEntryGroupEntryEvent": { "type": "object", "properties": { "background_color": { "type": "string" } } }, "models.TimeEntryGroupEntryProject": { "type": "object", "properties": { "color": { "type": "string" } } }, "models.TimeEntryGroupEntryTask": { "type": "object", "properties": { "color": { "type": "string" }, "project": { "$ref": "#/definitions/models.TimeEntryGroupEntryProject" } } }, "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" }, "member_discontinued": { "description": "MemberDiscontinued is true when the member's enrolment was\ndiscontinued and the cutoff has passed, regardless of the row's\ndate. Stamped on the list and details responses; omitted from\naction responses, same as SetupDiscontinued.", "type": "boolean" }, "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_discontinued": { "description": "SetupDiscontinued is true when SetupEndDate is set and already past,\ni.e. the setup accrues no new periods. Stamped on the list and\ndetails responses; omitted from action responses (submit, approve,\nwithdraw, request-changes) so they can't override a cached list\nrow's badge with an unstamped zero value.", "type": "boolean" }, "setup_end_date": { "description": "SetupEndDate is the parent setup's end_date, stamped by the list path\nalongside SetupPeriodicity; nil when the setup is open-ended.", "type": "string", "format": "date" }, "setup_id": { "description": "SetupID references the parent TimesheetSetup, which determines the\nperiod boundaries and the approval chain.", "type": "integer" }, "setup_periodicity": { "description": "SetupPeriodicity is the periodicity of the parent setup, stamped by\nthe list path on persisted and virtual rows alike; it has no DB\ncolumn, so it is empty on rows read straight from the database.", "enum": [ "weekly", "monthly", "days" ], "allOf": [ { "$ref": "#/definitions/models.Periodicity" } ] }, "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", "pause_starts_at", "paused", "payment_failed", "resumes_at", "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" }, "pause_starts_at": { "type": "string" }, "paused": { "description": "Paused is true while the organization is in the unpaid months of a self-serve pause, which is\nwhen products make it read-only; the subscription itself stays \"active\". PauseStartsAt is the\nfirst skipped renewal, where those months start, and ResumesAt the renewal billing restarts at.\nBoth are set from the moment the pause applies until billing restarts or the customer resumes,\nso clients can show a pause that has not started yet.", "type": "boolean" }, "payment_failed": { "type": "boolean" }, "resumes_at": { "type": "string" }, "start_date": { "type": "string" }, "subscription_created_at": { "type": "string" }, "subscription_updated_at": { "type": "string" }, "trial": { "$ref": "#/definitions/models.TrialResponse" } } }, "models.Trait": { "type": "object", "required": [ "created_at", "id", "name", "updated_at", "workspace_id" ], "properties": { "created_at": { "type": "string" }, "deleted_at": { "type": "string" }, "id": { "type": "integer" }, "member_ids": { "type": "array", "items": { "type": "integer" } }, "name": { "type": "string" }, "updated_at": { "type": "string" }, "workspace_id": { "type": "integer" } } }, "models.TraitCore": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "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" ] }, "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" }, "mcp_active_organization_id": { "description": "McpActiveOrganizationID is set by the public MCP as the user's currently active organization.", "type": "integer" }, "mcp_active_workspace_id": { "description": "McpActiveWorkspaceID is set by the public MCP as the user's currently active workspace.", "type": "integer" }, "new_users_trial_dismissed": { "type": "boolean" }, "notify_project_alerts": { "description": "NotifyProjectAlerts opts the user into project alert email/in-app/push (time-estimate, fixed-fee). Defaults to true.\nTime-tracking reminders are a separate product surface and are not gated by this flag.", "type": "boolean" }, "notify_project_member_added": { "description": "NotifyProjectMemberAdded opts the user into \"added to project\" email/in-app/push notifications. Defaults to true.", "type": "boolean" }, "notify_task_assigned": { "description": "NotifyTaskAssigned opts the user into task-assignment email/in-app/push notifications. Defaults to true.", "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" }, "project_privacy_education_dismissed": { "description": "ProjectPrivacyEducationDismissed reports whether the user acknowledged private-project education.", "type": "boolean" }, "reports_guide_dismissed": { "description": "ReportsGuideDismissed reports whether the user completed or dismissed reports guidance.", "type": "boolean" }, "reports_router_dismissed": { "description": "ReportsRouterDismissed reports whether the user resolved the reports chooser.", "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" }, "task_privacy_education_dismissed": { "description": "TaskPrivacyEducationDismissed reports whether the user acknowledged standalone-task privacy education.", "type": "boolean" }, "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" }, "timeline_education_dismissed": { "description": "TimelineEducationDismissed reports whether Timeline education was dismissed or covered by Plan onboarding.", "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" }, "work_preparation_reminders_disabled": { "description": "WorkPreparationRemindersDisabled turns off work-preparation reminders for this user in every workspace.", "type": "boolean" } } }, "models.UserWorkspaceSettings": { "type": "object", "required": [ "has_opened_focus" ], "properties": { "autolog_time": { "type": "boolean" }, "has_opened_focus": { "type": "boolean" }, "onboarding_intent": { "type": "string", "enum": [ "track", "plan", "projects" ] }, "onboarding_invited_user_ids": { "type": "array", "items": { "type": "integer" } }, "onboarding_project_id": { "type": "integer" }, "onboarding_step": { "type": "string", "enum": [ "team-size", "invite", "calendar", "first-entry", "welcome", "track", "project-sidebar", "project-list", "project-details", "project-estimate", "plan-calendar", "plan-task", "plan-details", "timeline", "capacity", "done" ] }, "onboarding_task_id": { "type": "integer" }, "onboarding_team_size": { "type": "string", "enum": [ "just-me", "2-5", "6-20", "21-50", "50+", "skipped" ] }, "work_introduction_dismissed": { "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 }, "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": { "description": "Whether `billable` was set on the entry (`manual`) or resolved from its task, else its project (`task_default`).", "enum": [ "manual", "task_default" ], "allOf": [ { "$ref": "#/definitions/models.BillableSource" } ] }, "calendar_event_id": { "type": "integer" }, "calendar_id": { "description": "CalendarID is the calendar service's calendar PK. It stays set after a calendar deselect clears 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": { "description": "Tracked duration in seconds; omitted while the timer is running and for an entry that is only planned.", "type": "integer" }, "id": { "type": "integer" }, "pattern_generated": { "description": "PatternGenerated is the response-facing derivative of GeneratedByTaskID:\ntrue when the entry was materialized by a series pattern.", "type": "boolean" }, "pattern_managed": { "description": "PatternManaged reports that the pattern engine owns this entry. Server-owned;\npresent in responses, never bindable from a payload.", "type": "boolean" }, "planned_at": { "type": "string", "format": "date-time" }, "planned_duration": { "description": "Planned duration in seconds.", "type": "integer" }, "planned_start": { "description": "Planned start, for time planned on the calendar.", "type": "string", "format": "date-time" }, "project_id": { "type": "integer" }, "start": { "description": "Start of the tracked time; omitted for an entry that is only planned.", "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" } } }, "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; 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" }, "designations": { "type": "array", "items": { "$ref": "#/definitions/models.TraitCore" } }, "email": { "type": "string" }, "groups": { "type": "array", "items": { "$ref": "#/definitions/organization.OrganizationUserGroupExtendedResponse" } }, "has_calendar_integration": { "description": "HasCalendarIntegration is true when the member has a calendar connected in Focus.\nThe field is present only when the request sets include_calendar_integration to\ntrue and the calendar lookup succeeded. The field is absent when the lookup\nfailed. Absent means unknown. It does not mean false.\nA member who connected a calendar in another product stays false here until they\nopen the Focus calendar integrations page.", "type": "boolean" }, "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" } } } }, "orgprivate.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" } } }, "orgprivate.TimeOffAbsenceReport": { "type": "object", "required": [ "end_date", "rows", "start_date", "totals" ], "properties": { "end_date": { "description": "EndDate is the period's last day: YYYY-MM-DD.", "type": "string" }, "rows": { "description": "Rows has one row per member and active policy with any non-zero figure, by member name.", "type": "array", "items": { "$ref": "#/definitions/orgprivate.TimeOffAbsenceReportRow" } }, "start_date": { "description": "StartDate is the period's first day: YYYY-MM-DD.", "type": "string" }, "totals": { "description": "Totals sums Rows.", "allOf": [ { "$ref": "#/definitions/orgprivate.TimeOffAbsenceReportTotals" } ] } } }, "orgprivate.TimeOffAbsenceReportRow": { "type": "object", "required": [ "absence_rate", "allowance_type", "balance", "category_emoji", "category_id", "category_name", "scheduled_after_period_end", "scheduled_in_period", "taken_in_period", "taken_through_period_end", "user_id", "user_name", "working_days_in_period" ], "properties": { "absence_rate": { "description": "AbsenceRate is TakenInPeriod divided by WorkingDaysInPeriod.", "type": "number" }, "allowance_type": { "description": "AllowanceType is the policy's allowance type.", "type": "string", "enum": [ "limited", "unlimited" ] }, "balance": { "description": "Balance is the sum of changes in EndDate's year up to EndDate, in days; 0 for an unlimited policy.", "type": "number" }, "category_emoji": { "description": "CategoryEmoji is the policy's emoji.", "type": "string" }, "category_id": { "description": "CategoryID is the policy.", "type": "integer" }, "category_name": { "description": "CategoryName is the policy's name.", "type": "string" }, "scheduled_after_period_end": { "description": "ScheduledAfterPeriodEnd is the days entries charge after EndDate.", "type": "number" }, "scheduled_in_period": { "description": "ScheduledInPeriod is the approved leave days in the period after today, plus pending ones when\nrequested.", "type": "number" }, "taken_in_period": { "description": "TakenInPeriod is the approved leave days in the period up to today.", "type": "number" }, "taken_through_period_end": { "description": "TakenThroughPeriodEnd is the days entries charged in EndDate's year up to EndDate.", "type": "number" }, "user_id": { "description": "UserID is the member.", "type": "integer" }, "user_name": { "description": "UserName is the member's name.", "type": "string" }, "working_days_in_period": { "description": "WorkingDaysInPeriod is the Monday to Friday days in the period.", "type": "integer" } } }, "orgprivate.TimeOffAbsenceReportTotals": { "type": "object", "required": [ "absence_rate", "balance", "scheduled_after_period_end", "scheduled_in_period", "taken_in_period", "taken_through_period_end", "user_count" ], "properties": { "absence_rate": { "description": "AbsenceRate is TakenInPeriod divided by working days times UserCount.", "type": "number" }, "balance": { "description": "Balance sums the rows' Balance.", "type": "number" }, "scheduled_after_period_end": { "description": "ScheduledAfterPeriodEnd sums the rows' ScheduledAfterPeriodEnd.", "type": "number" }, "scheduled_in_period": { "description": "ScheduledInPeriod sums the rows' ScheduledInPeriod.", "type": "number" }, "taken_in_period": { "description": "TakenInPeriod sums the rows' TakenInPeriod.", "type": "number" }, "taken_through_period_end": { "description": "TakenThroughPeriodEnd sums the rows' TakenThroughPeriodEnd.", "type": "number" }, "user_count": { "description": "UserCount is the members the report covers, including those without rows.", "type": "integer" } } }, "orgprivate.TimeOffBalance": { "type": "object", "required": [ "balance", "carried_over", "scheduled", "taken", "time_off_category_id" ], "properties": { "balance": { "description": "Balance is the sum of the as-of year's changes up to the as-of date, in days.", "type": "number" }, "carried_over": { "description": "CarriedOver is the sum of changes before the as-of year, in days. It does not expire.", "type": "number" }, "scheduled": { "description": "Scheduled is the days booked after the as-of date. Not yet subtracted from Balance.", "type": "number" }, "taken": { "description": "Taken is the days used in the as-of year up to the as-of date. Already subtracted from Balance.", "type": "number" }, "time_off_category_id": { "description": "TimeOffCategoryID is the policy.", "type": "integer" } } }, "orgprivate.TimeOffBalanceAdjustmentInput": { "type": "object", "required": [ "amount", "time_off_category_id", "user_id" ], "properties": { "amount": { "description": "Amount is the signed change in days; not zero.", "type": "number" }, "date": { "description": "Date is when the change takes effect, as RFC3339; its UTC day counts, and its year is the accrual\nyear. Now when omitted.", "type": "string" }, "note": { "description": "Note is recorded with the change; up to 2000 characters.", "type": "string", "maxLength": 2000 }, "time_off_category_id": { "description": "TimeOffCategoryID is the policy.", "type": "integer" }, "user_id": { "description": "UserID is the member.", "type": "integer" } } }, "orgprivate.TimeOffBalanceChange": { "type": "object", "required": [ "accrual_year", "amount", "created_at", "effective_date", "id", "note", "time_off_category_id", "type" ], "properties": { "accrual_month": { "description": "AccrualMonth is the month of a monthly accrual; omitted otherwise.", "type": "integer" }, "accrual_year": { "description": "AccrualYear is the year the change counts toward.", "type": "integer" }, "amount": { "description": "Amount is the signed change in days.", "type": "number" }, "created_at": { "description": "CreatedAt is when the change was recorded.", "type": "string" }, "created_by": { "description": "CreatedBy is the account id of the member who made the change; omitted for automatic changes.", "type": "integer" }, "effective_date": { "description": "EffectiveDate is the day the change takes effect.", "type": "string" }, "id": { "description": "ID is the change's id.", "type": "integer" }, "note": { "description": "Note is the note recorded with the change; empty on used changes.", "type": "string" }, "remaining_balance": { "description": "RemainingBalance is the policy balance after this change.", "type": "number" }, "time_off_category_id": { "description": "TimeOffCategoryID is the policy.", "type": "integer" }, "time_off_end_date": { "description": "TimeOffEndDate is the end of the entry that used the days; set on used changes only.", "type": "string" }, "time_off_id": { "description": "TimeOffID is the entry that used the days; set on used changes only.", "type": "integer" }, "time_off_start_date": { "description": "TimeOffStartDate is the start of the entry that used the days; set on used changes only.", "type": "string" }, "type": { "description": "Type is earned (accrual), used (by an entry), adjustment (manual), initial_seed (starting balance)\nor carry_over (days above MaxCarryOverAmount removed at the new year).", "type": "string", "enum": [ "earned", "used", "adjustment", "initial_seed", "carry_over" ] } } }, "orgprivate.TimeOffBalanceChangesPage": { "type": "object", "required": [ "data", "page", "rows" ], "properties": { "data": { "description": "Data is the page's changes.", "type": "array", "items": { "$ref": "#/definitions/orgprivate.TimeOffBalanceChange" } }, "page": { "description": "Page is the 1-based page number.", "type": "integer" }, "rows": { "description": "Rows is the page size.", "type": "integer" }, "total": { "description": "Total is the number of changes across all pages; omitted when zero.", "type": "integer" } } }, "orgprivate.TimeOffBalanceImportFailedRow": { "type": "object", "required": [ "code", "row" ], "properties": { "code": { "description": "Code is unknown_member (not in the organization), duplicate_member (listed earlier) or\namount_invalid (outside the allowed range).", "type": "string", "enum": [ "unknown_member", "duplicate_member", "amount_invalid" ] }, "row": { "description": "Row is the 1-based position in Rows.", "type": "integer" } } }, "orgprivate.TimeOffBalanceImportInput": { "type": "object", "required": [ "category_id", "rows" ], "properties": { "category_id": { "description": "CategoryID is the policy: limited, yearly or one-off, with a yearly allowance above 0.", "type": "integer" }, "rows": { "description": "Rows are the members' starting balances; 1 to 10,000, each member once.", "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/orgprivate.TimeOffBalanceImportRow" } } } }, "orgprivate.TimeOffBalanceImportResult": { "type": "object", "required": [ "failures", "skipped", "written" ], "properties": { "failures": { "description": "Failures are invalid rows; any failure means nothing was written.", "type": "array", "items": { "$ref": "#/definitions/orgprivate.TimeOffBalanceImportFailedRow" } }, "skipped": { "description": "Skipped are rows left unchanged; the other rows are still written.", "type": "array", "items": { "$ref": "#/definitions/orgprivate.TimeOffBalanceImportSkippedRow" } }, "written": { "description": "Written is the number of members whose starting balance was set; 0 when there are Failures.", "type": "integer" } } }, "orgprivate.TimeOffBalanceImportRow": { "type": "object", "required": [ "amount", "user_account_id" ], "properties": { "amount": { "description": "Amount is the member's starting balance for the current year, in days: 0 to the policy's\nDefaultAmountPerYear plus MaxCarryOverAmount.", "type": "number" }, "user_account_id": { "description": "UserAccountID is the member.", "type": "integer" } } }, "orgprivate.TimeOffBalanceImportSkippedRow": { "type": "object", "required": [ "code", "row", "user_account_id" ], "properties": { "code": { "description": "Code is not_eligible: the member is inactive or not assigned the Time Off module.", "type": "string", "enum": [ "not_eligible" ] }, "row": { "description": "Row is the 1-based position in Rows.", "type": "integer" }, "user_account_id": { "description": "UserAccountID is the member.", "type": "integer" } } }, "orgprivate.TimeOffCategory": { "type": "object", "required": [ "accrual_frequency", "allow_negative_balance", "allowance_type", "auto_approve_under_days", "created_at", "default_amount_per_year", "description", "emoji", "id", "is_system_default", "max_carry_over_amount", "name", "organization_id", "prorate", "updated_at" ], "properties": { "accrual_frequency": { "description": "AccrualFrequency is how the allowance is credited: yearly, monthly (a twelfth each month)\nor one_off (once, as a starting balance).", "type": "string", "enum": [ "yearly", "monthly", "one_off" ] }, "allow_negative_balance": { "description": "AllowNegativeBalance lets a member's own request take a limited balance below zero.", "type": "boolean" }, "allowance_type": { "description": "AllowanceType is limited, tracked against a balance, or unlimited.", "type": "string", "enum": [ "limited", "unlimited" ] }, "archived_at": { "description": "ArchivedAt is when the policy was archived; omitted while it is active.", "type": "string" }, "auto_approve_under_days": { "description": "AutoApproveUnderDays is the longest own request, in days, a member can have approved without review.\nA limited policy also checks the balance, so a request within the limit can still go to review.\n0 turns it off.", "type": "integer" }, "carry_over_expiry_months": { "description": "CarryOverExpiryMonths is how many months carried-over days are meant to last; omitted when unset.\nStored only, not applied yet: carried-over days do not expire.", "type": "integer" }, "created_at": { "description": "CreatedAt is when the policy was created.", "type": "string" }, "default_amount_per_year": { "description": "DefaultAmountPerYear is the yearly allowance in days. Unused by unlimited policies.", "type": "integer" }, "description": { "description": "Description is the policy's description; null when unset.", "type": "string" }, "emoji": { "description": "Emoji is shown next to the name.", "type": "string" }, "id": { "description": "ID is the policy's id. Entries reference it as time_off_category_id.", "type": "integer" }, "is_system_default": { "description": "IsSystemDefault marks the organization's default policy, created automatically.", "type": "boolean" }, "max_carry_over_amount": { "description": "MaxCarryOverAmount is how many unused days carry into the next year on a yearly policy.", "type": "integer" }, "name": { "description": "Name is the policy's name.", "type": "string" }, "organization_id": { "description": "OrganizationID is the organization the policy belongs to.", "type": "integer" }, "policy_link": { "description": "PolicyLink is a URL to the written policy; omitted when unset.", "type": "string" }, "prorate": { "description": "Prorate is when proration was turned on; null when off. With proration, a member's first-year\nallowance covers only the months left after the later of this date and their join date.", "type": "string" }, "updated_at": { "description": "UpdatedAt is when the policy was last changed.", "type": "string" } } }, "orgprivate.TimeOffCategoryCreateInput": { "type": "object", "required": [ "allow_negative_balance", "auto_approve_under_days", "default_amount_per_year", "description", "emoji", "max_carry_over_amount", "name", "prorate" ], "properties": { "accrual_frequency": { "description": "AccrualFrequency is how the allowance is credited: yearly (default), monthly (a twelfth each month)\nor one_off (once, as a starting balance). Unlimited policies are always one_off. Fixed after creation.", "type": "string", "enum": [ "yearly", "monthly", "one_off" ] }, "allow_negative_balance": { "description": "AllowNegativeBalance lets a member's own request take a limited balance below zero.", "type": "boolean" }, "allowance_type": { "description": "AllowanceType is limited (default), tracked against a balance, or unlimited. Fixed after creation.", "type": "string", "enum": [ "limited", "unlimited" ] }, "auto_approve_under_days": { "description": "AutoApproveUnderDays is the longest own request, in days, a member can have approved without review.\nA limited policy also checks the balance. 0 turns it off.", "type": "integer", "minimum": 0 }, "carry_over_expiry_months": { "description": "CarryOverExpiryMonths is how many months carried-over days are meant to last, at least 1. Stored only,\nnot applied yet: carried-over days do not expire.", "type": "integer", "minimum": 1 }, "default_amount_per_year": { "description": "DefaultAmountPerYear is the yearly allowance in days, up to 999. Unused by unlimited policies.", "type": "integer", "maximum": 999, "minimum": 0 }, "description": { "description": "Description is the policy's description; up to 1000 characters.", "type": "string", "maxLength": 1000 }, "emoji": { "description": "Emoji is shown next to the name.", "type": "string" }, "max_carry_over_amount": { "description": "MaxCarryOverAmount is how many unused days carry into the next year on a yearly policy, up to 999.", "type": "integer", "maximum": 999, "minimum": 0 }, "name": { "description": "Name is the policy's name; up to 255 characters.", "type": "string", "maxLength": 255 }, "policy_link": { "description": "PolicyLink is a URL to the written policy; up to 2048 characters.", "type": "string", "maxLength": 2048 }, "prorate": { "description": "Prorate true sets the proration date to now, also when proration is already on; false turns it off.\nWith proration, a member's first-year allowance covers only the months left after the later of that\ndate and their join date.", "type": "boolean" } } }, "orgprivate.TimeOffCategoryUpdateInput": { "type": "object", "required": [ "allow_negative_balance", "auto_approve_under_days", "default_amount_per_year", "description", "emoji", "max_carry_over_amount", "name", "prorate" ], "properties": { "allow_negative_balance": { "description": "AllowNegativeBalance lets a member's own request take a limited balance below zero.", "type": "boolean" }, "auto_approve_under_days": { "description": "AutoApproveUnderDays is the longest own request, in days, a member can have approved without review.\nA limited policy also checks the balance. 0 turns it off.", "type": "integer", "minimum": 0 }, "carry_over_expiry_months": { "description": "CarryOverExpiryMonths is how many months carried-over days are meant to last, at least 1. Stored only,\nnot applied yet: carried-over days do not expire.", "type": "integer", "minimum": 1 }, "default_amount_per_year": { "description": "DefaultAmountPerYear is the yearly allowance in days, up to 999. Unused by unlimited policies.", "type": "integer", "maximum": 999, "minimum": 0 }, "description": { "description": "Description is the policy's description; up to 1000 characters.", "type": "string", "maxLength": 1000 }, "emoji": { "description": "Emoji is shown next to the name.", "type": "string" }, "max_carry_over_amount": { "description": "MaxCarryOverAmount is how many unused days carry into the next year on a yearly policy, up to 999.", "type": "integer", "maximum": 999, "minimum": 0 }, "name": { "description": "Name is the policy's name; up to 255 characters.", "type": "string", "maxLength": 255 }, "policy_link": { "description": "PolicyLink is a URL to the written policy; up to 2048 characters.", "type": "string", "maxLength": 2048 }, "prorate": { "description": "Prorate true sets the proration date to now, also when proration is already on; false turns it off.\nWith proration, a member's first-year allowance covers only the months left after the later of that\ndate and their join date.", "type": "boolean" } } }, "orgprivate.TimeOffEntriesPage": { "type": "object", "required": [ "data", "page", "rows" ], "properties": { "data": { "description": "Data is the page's entries.", "type": "array", "items": { "$ref": "#/definitions/orgprivate.TimeOffEntryWithUsers" } }, "page": { "description": "Page is the 1-based page number.", "type": "integer" }, "rows": { "description": "Rows is the page size.", "type": "integer" }, "total": { "description": "Total is the number of entries across all pages; omitted when zero.", "type": "integer" } } }, "orgprivate.TimeOffEntry": { "type": "object", "required": [ "created_at", "daily_breakdown", "days_taken", "end_date", "id", "note", "organization_id", "rejection_reason", "start_date", "status", "updated_at", "user_id" ], "properties": { "approved_at": { "description": "ApprovedAt is when the entry was approved; omitted when it never was, and for entries created\nthrough the API.", "type": "string" }, "approver_id": { "description": "ApproverID is the member who approved or rejected the entry; omitted when no member did.", "type": "integer" }, "created_at": { "description": "CreatedAt is when the entry was created.", "type": "string" }, "created_by": { "description": "CreatedBy is the member who created the entry; omitted when not recorded.", "type": "integer" }, "daily_breakdown": { "description": "DailyBreakdown is the entry's day-by-day count; empty when it has none.", "type": "array", "items": { "$ref": "#/definitions/orgprivate.TimeOffEntryDay" } }, "days_taken": { "description": "DaysTaken is the entry's day count, the sum of DailyBreakdown.", "type": "number" }, "end_date": { "description": "EndDate is the day the entry ends, in UTC: YYYY-MM-DDT00:00:00.", "type": "string" }, "id": { "description": "ID is the entry's id; the per-user entry endpoints call it timeoff_id.", "type": "integer" }, "note": { "description": "Note is the requester's note.", "type": "string" }, "organization_id": { "description": "OrganizationID is the entry's organization.", "type": "integer" }, "rejection_reason": { "description": "RejectionReason is the reason given on rejection; empty otherwise.", "type": "string" }, "start_date": { "description": "StartDate is when the entry starts, in UTC without an offset: YYYY-MM-DDTHH:MM:SS.", "type": "string" }, "status": { "description": "Status is the approval state.", "type": "string", "enum": [ "pending", "approved", "rejected", "canceled" ] }, "time_off_category_id": { "description": "TimeOffCategoryID is the entry's policy; omitted when it has none.", "type": "integer" }, "updated_at": { "description": "UpdatedAt is when the entry was last changed.", "type": "string" }, "user_id": { "description": "UserID is the member the entry belongs to.", "type": "integer" } } }, "orgprivate.TimeOffEntryDay": { "type": "object", "required": [ "date", "taken" ], "properties": { "date": { "description": "Date is the day, in UTC: YYYY-MM-DDT00:00:00.", "type": "string" }, "taken": { "description": "Taken is the part of the day taken, 0 to 1.", "type": "number" } } }, "orgprivate.TimeOffEntryWithUsers": { "type": "object", "required": [ "approver_email", "approver_name", "created_at", "creator_email", "creator_name", "daily_breakdown", "days_taken", "end_date", "id", "note", "organization_id", "rejection_reason", "requester_email", "requester_name", "requester_user_account_id", "start_date", "status", "updated_at", "user_id" ], "properties": { "approved_at": { "description": "ApprovedAt is when the entry was approved; omitted when it never was, and for entries created\nthrough the API.", "type": "string" }, "approver_email": { "description": "ApproverEmail is the approver's email; empty without an approver.", "type": "string" }, "approver_id": { "description": "ApproverID is the member who approved or rejected the entry; omitted when no member did.", "type": "integer" }, "approver_name": { "description": "ApproverName is the approver's name; empty without an approver.", "type": "string" }, "approver_user_account_id": { "description": "ApproverUserAccountID equals ApproverID.", "type": "integer" }, "created_at": { "description": "CreatedAt is when the entry was created.", "type": "string" }, "created_by": { "description": "CreatedBy is the member who created the entry; omitted when not recorded.", "type": "integer" }, "creator_email": { "description": "CreatorEmail is the creator's email; empty when CreatedBy is omitted.", "type": "string" }, "creator_name": { "description": "CreatorName is the creator's name; empty when CreatedBy is omitted.", "type": "string" }, "daily_breakdown": { "description": "DailyBreakdown is the entry's day-by-day count; empty when it has none.", "type": "array", "items": { "$ref": "#/definitions/orgprivate.TimeOffEntryDay" } }, "days_taken": { "description": "DaysTaken is the entry's day count, the sum of DailyBreakdown.", "type": "number" }, "end_date": { "description": "EndDate is the day the entry ends, in UTC: YYYY-MM-DDT00:00:00.", "type": "string" }, "id": { "description": "ID is the entry's id; the per-user entry endpoints call it timeoff_id.", "type": "integer" }, "note": { "description": "Note is the requester's note.", "type": "string" }, "organization_id": { "description": "OrganizationID is the entry's organization.", "type": "integer" }, "rejection_reason": { "description": "RejectionReason is the reason given on rejection; empty otherwise.", "type": "string" }, "requester_email": { "description": "RequesterEmail is the member's email.", "type": "string" }, "requester_name": { "description": "RequesterName is the member's name.", "type": "string" }, "requester_user_account_id": { "description": "RequesterUserAccountID is the entry's member; equals UserID.", "type": "integer" }, "start_date": { "description": "StartDate is when the entry starts, in UTC without an offset: YYYY-MM-DDTHH:MM:SS.", "type": "string" }, "status": { "description": "Status is the approval state.", "type": "string", "enum": [ "pending", "approved", "rejected", "canceled" ] }, "time_off_category_id": { "description": "TimeOffCategoryID is the entry's policy; omitted when it has none.", "type": "integer" }, "updated_at": { "description": "UpdatedAt is when the entry was last changed.", "type": "string" }, "user_id": { "description": "UserID is the member the entry belongs to.", "type": "integer" } } }, "orgprivate.TimeOffRejectInput": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "description": "Reason is shown to the requester; optional.", "type": "string" } } }, "orgprivate.TimeOffTimelineEntry": { "type": "object", "required": [ "days_span", "days_taken", "end_date", "id", "requester_name", "start_date", "status", "user_id" ], "properties": { "days_span": { "description": "DaysSpan is the number of calendar days from StartDate to EndDate, both included.", "type": "integer" }, "days_taken": { "description": "DaysTaken is the entry's day count.", "type": "number" }, "end_date": { "description": "EndDate is the day the entry ends, in UTC: YYYY-MM-DDT00:00:00.", "type": "string" }, "id": { "description": "ID is the entry's id.", "type": "integer" }, "requester_name": { "description": "RequesterName is the member's name.", "type": "string" }, "start_date": { "description": "StartDate is the entry's first day, in UTC: YYYY-MM-DDT00:00:00.", "type": "string" }, "status": { "description": "Status is the approval state.", "type": "string", "enum": [ "pending", "approved", "rejected", "canceled" ] }, "time_off_category_id": { "description": "TimeOffCategoryID is the entry's policy; omitted when it has none.", "type": "integer" }, "user_id": { "description": "UserID is the member the entry belongs to.", "type": "integer" } } }, "orgprivate.TimeOffUserBalance": { "type": "object", "required": [ "balance", "carried_over", "scheduled", "taken", "time_off_category_id", "user_id" ], "properties": { "balance": { "description": "Balance is the sum of the as-of year's changes up to the as-of date, in days.", "type": "number" }, "carried_over": { "description": "CarriedOver is the sum of changes before the as-of year, in days. It does not expire.", "type": "number" }, "scheduled": { "description": "Scheduled is the days booked after the as-of date. Not yet subtracted from Balance.", "type": "number" }, "taken": { "description": "Taken is the days used in the as-of year up to the as-of date. Already subtracted from Balance.", "type": "number" }, "time_off_category_id": { "description": "TimeOffCategoryID is the policy.", "type": "integer" }, "user_id": { "description": "UserID is the member.", "type": "integer" } } }, "orgprivate.TimeOffWhosOutEntry": { "type": "object", "required": [ "display_name", "end_date", "id", "start_date", "user_account_id" ], "properties": { "display_name": { "description": "DisplayName is the member's name.", "type": "string" }, "end_date": { "description": "EndDate is the absence's last day: YYYY-MM-DD.", "type": "string" }, "id": { "description": "ID is the entry's id.", "type": "integer" }, "start_date": { "description": "StartDate is the absence's first day: YYYY-MM-DD.", "type": "string" }, "user_account_id": { "description": "UserAccountID is the absent member.", "type": "integer" } } }, "presence.PlatformLastSeen": { "type": "object", "required": [ "last_seen_at", "platform" ], "properties": { "last_seen_at": { "type": "string", "format": "date-time" }, "platform": { "$ref": "#/definitions/events.PlatformOrigin" } } }, "project.BulkArchivePayload": { "type": "object", "required": [ "project_ids" ], "properties": { "project_ids": { "type": "array", "maxItems": 100, "minItems": 1, "items": { "type": "integer" } } } }, "project.BulkGroupEntry": { "type": "object", "required": [ "group_id", "role_id" ], "properties": { "group_id": { "type": "integer" }, "role_id": { "description": "Used only when adding or restoring a team; an existing team keeps its current role.", "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.ClonedProjectResponse": { "type": "object", "required": [ "active", "auto_compute_estimates", "billable", "completion_mode", "created_at", "draft", "estimate_source", "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" }, "dropped_assignments": { "type": "array", "items": { "$ref": "#/definitions/task.DroppedAssignment" } }, "end_date": { "type": "string", "format": "date" }, "estimate_source": { "enum": [ "manual", "tasks" ], "allOf": [ { "$ref": "#/definitions/models.ProjectEstimateSource" } ] }, "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" } } }, "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": { "auto_compute_estimates": { "type": "boolean" }, "completion_mode": { "type": "string", "enum": [ "manual", "automatic" ] }, "end_date": { "type": "string", "format": "date" }, "estimate_source": { "type": "string", "enum": [ "manual", "tasks" ] }, "estimated_mins": { "type": "integer", "minimum": 0, "x-nullable": true }, "fixed_fee": { "allOf": [ { "$ref": "#/definitions/project.FixedFeePayload" } ], "x-nullable": true }, "name": { "type": "string" }, "pinned": { "type": "boolean" }, "rollover_mode": { "type": "string", "enum": [ "expire", "carry_all", "carry_over" ] }, "rrule": { "type": "string" }, "start_date": { "type": "string", "format": "date" } } }, "project.CreateInstancePayload": { "type": "object", "properties": { "auto_compute_estimates": { "type": "boolean", "x-nullable": true }, "billable": { "type": "boolean" }, "client_id": { "type": "integer", "x-nullable": true }, "description": { "type": "string", "x-nullable": true }, "estimate_source": { "type": "string", "enum": [ "manual", "tasks" ] }, "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", "estimate_source", "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" }, "estimate_source": { "enum": [ "manual", "tasks" ], "allOf": [ { "$ref": "#/definitions/models.ProjectEstimateSource" } ] }, "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" }, "estimate_source": { "type": "string", "enum": [ "manual", "tasks" ] }, "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.ListResponse": { "type": "object", "required": [ "data", "page", "per_page", "total" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.ProjectWithAggregations" } }, "no_project_picker_parent_group_count": { "type": "integer" }, "no_project_task_count": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } }, "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", "x-nullable": true }, "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 }, "estimate_source": { "type": "string", "enum": [ "manual", "tasks" ] }, "estimated_mins": { "type": "integer", "minimum": 0, "x-nullable": true }, "fixed_fee": { "allOf": [ { "$ref": "#/definitions/project.FixedFeePayload" } ], "x-nullable": true }, "name": { "type": "string", "minLength": 1 }, "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", "x-nullable": true }, "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 }, "estimate_source": { "type": "string", "enum": [ "manual", "tasks" ] }, "estimated_mins": { "type": "integer", "minimum": 0, "x-nullable": true }, "fixed_fee": { "allOf": [ { "$ref": "#/definitions/project.FixedFeePayload" } ], "x-nullable": true }, "groups": { "description": "Omit to leave teams unchanged; an empty array removes non-manager teams. Existing roles and manager teams are preserved.", "type": "array", "uniqueItems": true, "items": { "$ref": "#/definitions/project.BulkGroupEntry" }, "x-nullable": true }, "id": { "type": "integer" }, "name": { "type": "string", "minLength": 1 }, "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" }, "estimate_source": { "type": "string", "enum": [ "manual", "tasks" ], "x-nullable": true }, "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", "role_id" ], "properties": { "group_id": { "type": "integer" }, "manager": { "type": "boolean", "x-nullable": true }, "role_id": { "type": "integer" } } }, "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" } } }, "publicshare.ChartRequest": { "type": "object", "properties": { "chart_key": { "type": "string" } } }, "publicshare.OpenResponse": { "type": "object", "required": [ "chart_keys", "owner", "presentation", "view", "workspace" ], "properties": { "chart_keys": { "type": "array", "items": { "type": "string" } }, "dictionary": { "$ref": "#/definitions/dictionary.Dictionary" }, "owner": { "$ref": "#/definitions/publicshare.OwnerSummary" }, "period": { "type": "object" }, "presentation": { "type": "object" }, "view": { "$ref": "#/definitions/sharedreport.SharedViewSummary" }, "window": { "description": "Window is the window the charts are served on, resolved in the\nowner's calendar; absent for a share that stores no period.", "allOf": [ { "$ref": "#/definitions/sharedreportdates.Window" } ] }, "workspace": { "$ref": "#/definitions/publicshare.WorkspaceSummary" } } }, "publicshare.OwnerSummary": { "type": "object", "required": [ "display_name" ], "properties": { "display_name": { "type": "string" } } }, "publicshare.WorkspaceSummary": { "type": "object", "required": [ "currency", "id", "organization_id" ], "properties": { "currency": { "type": "string" }, "id": { "type": "integer" }, "organization_id": { "type": "integer" }, "utilization_target_percent": { "description": "UtilizationTargetPercent is the target as the owner sees it: the\ndefault when the workspace never set one, or when the owner may not\nview it. Always sent; optional in the schema so a client whose\nfixtures predate it still type-checks.", "type": "integer" } } }, "pushtarget.Target": { "type": "object", "required": [ "calendar_id", "integration_id" ], "properties": { "calendar_id": { "type": "integer" }, "integration_id": { "type": "integer" } } }, "rate.ConflictCheckResult": { "type": "object", "properties": { "affected_period_count": { "type": "integer" }, "deleted": { "type": "array", "items": { "$ref": "#/definitions/rate.RateAPI" } }, "modified": { "type": "array", "items": { "$ref": "#/definitions/rate.ModifiedRate" } }, "period_conflict_count": { "type": "integer" } } }, "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" } } }, "reportschedule.ViewSchedulePayload": { "type": "object", "required": [ "cadence", "charts", "time" ], "properties": { "cadence": { "enum": [ "daily", "weekly", "monthly" ], "allOf": [ { "$ref": "#/definitions/models.ScheduleCadence" } ] }, "charts": { "description": "Charts is every chart the view type renders, each with the query\nthat serves it. Opaque and FE-defined.", "type": "object", "additionalProperties": { "$ref": "#/definitions/sharedreport.ChartPayload" } }, "day": { "description": "Day is required for weekly (a weekday, 0=Sunday) and monthly (1-28),\nand refused for daily.", "type": "integer" }, "period": { "description": "Period is the share's period: a preset or both from and to dates,\nanything else 400 invalid_shared_period. Optional: a share may store\nnone, and both spellings of \"none\" -- absent and an explicit null --\nstore as absent.", "type": "object" }, "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": {} }, "feature": { "type": "string" }, "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.BulkWorkingHoursInput": { "type": "object", "required": [ "schedule", "user_ids" ], "properties": { "schedule": { "description": "Schedule is either a single row without a weekday (a weekly total) or up to 56 weekday rows of at most 24 hours\neach; several rows may share a weekday (time blocks).", "type": "array", "maxItems": 56, "minItems": 1, "items": { "$ref": "#/definitions/shareddata.WorkingHoursScheduleRow" } }, "user_ids": { "description": "UserIDs are the organization members to set the schedule for: 1 to 100 distinct ids.", "type": "array", "maxItems": 100, "minItems": 1, "uniqueItems": true, "items": { "type": "integer" } } } }, "shareddata.BulkWorkingHoursResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "description": "Results holds one entry per requested user id, in request order.", "type": "array", "items": { "$ref": "#/definitions/shareddata.MemberWorkingHoursResult" } } } }, "shareddata.MemberWorkingHoursResult": { "type": "object", "required": [ "user_id", "working_hours" ], "properties": { "user_id": { "description": "UserID is the member this result is for.", "type": "integer" }, "working_hours": { "description": "WorkingHours is the member's schedule after the request.", "type": "array", "items": { "$ref": "#/definitions/shareddata.WorkingHours" } } } }, "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": { "starting_hours": { "type": "number", "maximum": 24, "minimum": 0 }, "weekday": { "type": "integer", "maximum": 6, "minimum": 0 }, "working_hours": { "type": "number", "maximum": 168 } } }, "shareddata.WorkingHoursScheduleRow": { "type": "object", "required": [ "working_hours" ], "properties": { "starting_hours": { "description": "StartingHours is the hour of the day (0-24) the row starts at; it requires a weekday. Omit it to keep the\nstart of the user's existing row for that weekday when it is the weekday's only row.", "type": "number", "maximum": 24, "minimum": 0 }, "weekday": { "description": "Weekday is the day of the week (0-6) the hours apply to. Omit it for a weekly total.", "type": "integer", "maximum": 6, "minimum": 0 }, "working_hours": { "description": "Hours is the number of working hours, greater than 0 and at most 168.", "type": "number", "maximum": 168 } } }, "shareddata.WorkingHoursUpdateInput": { "type": "object", "required": [ "working_hour_id", "working_hours" ], "properties": { "starting_hours": { "type": "number", "maximum": 24, "minimum": 0 }, "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", "shared_report_id" ], "properties": { "grants": { "type": "array", "items": { "$ref": "#/definitions/models.SharedReportGrant" } }, "link": { "description": "Link is the share's live public link, null while the share is\nprivate. Only the owner reads this response, so the token is\ntheirs to see.", "allOf": [ { "$ref": "#/definitions/models.SharedReportLink" } ] }, "locked": { "description": "Locked is whether recipients are kept on the share's period rather\nthan choosing their own dates. Resolved: a share whose lock was never\nset is locked.", "type": "boolean" }, "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" }, "shared_report_id": { "description": "SharedReportID repeats shared_report.id at the top level: it is\nthe identity the client's cache patches the share by, the same\nkey the shared-by-me listing carries.", "type": "integer" } } }, "sharedreport.ChartPayload": { "type": "object", "required": [ "flexq_query" ], "properties": { "flexq_query": { "type": "object" } } }, "sharedreport.DatesResponse": { "type": "object", "properties": { "locked": { "description": "Locked is the share's lock, sent whether or not there is a Window.\nResolved: a share whose lock was never set is locked.", "type": "boolean" }, "window": { "$ref": "#/definitions/sharedreportdates.Window" } } }, "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.LinkPayload": { "type": "object", "properties": { "expires_at": { "type": "string", "format": "date-time" } } }, "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.SetDatesLockPayload": { "type": "object", "required": [ "locked" ], "properties": { "locked": { "type": "boolean" } } }, "sharedreport.ShareManyPayload": { "type": "object", "required": [ "charts", "grantees" ], "properties": { "charts": { "type": "object", "additionalProperties": { "$ref": "#/definitions/sharedreport.ChartPayload" } }, "grantees": { "description": "Grantees may be empty, never absent: an empty list creates the share\nwith nobody on it, so its owner can publish a link before sharing it.", "type": "array", "maxItems": 100, "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" } }, "link": { "description": "Link is the share's live public link, absent while the share is\nprivate -- the listing is where a published share is told apart.", "allOf": [ { "$ref": "#/definitions/models.SharedReportLink" } ] }, "link_serving": { "description": "LinkServing is whether Link serves the report right now. A live link\non a share that stores no period answers not-found until a period is\nshared again.", "type": "boolean" }, "locked": { "description": "Locked is whether recipients are kept on Period rather than choosing\ntheir own dates. Resolved: a share whose lock was never set is locked.", "type": "boolean" }, "period": { "description": "Period is the window recipients land on, a preset or fixed dates.", "type": "object" }, "schedule": { "$ref": "#/definitions/models.ReportScheduleWithRecipients" }, "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" } }, "locked": { "description": "Locked is whether a period sent with a chart read is discarded. It\nis also discarded, locked or not, on a share with no Period.\nResolved: a share whose lock was never set is locked.", "type": "boolean" }, "owner_user_id": { "type": "integer" }, "period": { "type": "object" }, "presentation": { "type": "object" }, "view": { "$ref": "#/definitions/sharedreport.SharedViewSummary" } } }, "sharedreportdates.Range": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "sharedreportdates.Window": { "type": "object", "required": [ "locked", "range", "rolling", "substituted" ], "properties": { "locked": { "type": "boolean" }, "period": { "type": "object" }, "range": { "$ref": "#/definitions/sharedreportdates.Range" }, "rolling": { "type": "boolean" }, "substituted": { "type": "boolean" } } }, "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", "granted", "organization_id", "price", "product", "subscription", "subscription_item", "track_subscription" ], "properties": { "focus_trial_ended_at": { "type": "string", "format": "date-time", "x-nullable": true }, "granted": { "description": "Granted reports an entitlement the organization holds without paying for it: the\nStripe-backed fields are empty because no Stripe subscription backs the grant.", "type": "boolean" }, "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.MergePayload": { "type": "object", "required": [ "source_ids", "target_id" ], "properties": { "source_ids": { "description": "The tags merged away — retagged onto the target, then soft-deleted.", "type": "array", "maxItems": 10, "minItems": 1, "items": { "type": "integer" } }, "target_id": { "description": "The tag that survives and receives every attachment.", "type": "integer" } } }, "tag.Payload": { "type": "object", "required": [ "color", "name" ], "properties": { "color": { "type": "string" }, "name": { "type": "string" } } }, "tag.TimeEntryCount": { "type": "object", "required": [ "count", "has_more" ], "properties": { "count": { "type": "integer" }, "has_more": { "type": "boolean" } } }, "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", "degraded_integrations", "time_entries_created", "time_entries_materialized", "time_entries_relinked" ], "properties": { "changed": { "type": "integer" }, "degraded_integrations": { "type": "array", "items": { "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": { "description": "Send together with start_date; must be on or after start_date.", "type": "string", "format": "date" }, "estimate_type": { "type": "string", "enum": [ "daily", "total" ] }, "estimated_mins": { "type": "integer", "minimum": 0 }, "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": { "description": "Send together with end_date; a date without the other is rejected.", "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.CreatePayloadWithRecurringRule": { "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": { "description": "Send together with start_date; must be on or after start_date.", "type": "string", "format": "date" }, "estimate_type": { "type": "string", "enum": [ "daily", "total" ] }, "estimated_mins": { "type": "integer", "minimum": 0 }, "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_rule": { "description": "Makes the new task repeat (POST /tasks only, not with rrule): an RRULE whose DTSTART gives the dates if none are sent.", "type": "string", "x-nullable": true }, "rollup_enabled": { "type": "boolean" }, "rrule": { "type": "string", "x-nullable": true }, "start_date": { "description": "Send together with end_date; a date without the other is rejected.", "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": { "description": "Send together with start_date; must be on or after start_date.", "type": "string", "format": "date" }, "estimate_type": { "type": "string", "enum": [ "daily", "total" ] }, "estimated_mins": { "type": "integer", "minimum": 0 }, "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": { "description": "Send together with end_date; a date without the other is rejected.", "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.DroppedAssignment": { "type": "object", "required": [ "reason", "task_id", "task_name", "user_ids" ], "properties": { "reason": { "type": "string" }, "task_id": { "type": "integer" }, "task_name": { "type": "string" }, "user_ids": { "type": "array", "items": { "type": "integer" } } } }, "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": { "after_task_id": { "type": "integer", "x-nullable": true }, "allocation_unit": { "type": "string", "enum": [ "percent", "flat" ] }, "assignee_user_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "auto_log_time": { "type": "boolean", "x-nullable": true }, "billable": { "type": "boolean", "x-nullable": true }, "color": { "type": "string", "x-nullable": true }, "custom_fields": { "type": "object", "x-nullable": true }, "description": { "type": "string", "x-nullable": true }, "end_date": { "description": "Send together with start_date; must be on or after start_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", "minLength": 1 }, "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_rule": { "description": "Makes the task repeat (PATCH /tasks/{id} only, sent alone; null is not supported yet): an RRULE whose DTSTART gives the dates if none are set.", "type": "string" }, "recurring_task_id": { "type": "integer", "x-nullable": true }, "repeat_planned_time_entry_id": { "description": "RepeatPlannedTimeEntryID is the declared initial-selection input that\nwill start a series from an existing planned entry (PR 11). Any\nsupplied value — an ID or JSON null — is rejected until then; the\ncontract is declared in docs/recurring-pr2a-additive-schema.md.\njson.RawMessage keeps absent distinguishable from explicit null on\ndecode and is omitted on marshal when never set.", "type": "integer", "x-nullable": true }, "rollup_enabled": { "type": "boolean" }, "rrule": { "type": "string", "x-nullable": true }, "start_date": { "description": "Send together with end_date; a date without the other is rejected.", "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": { "after_task_id": { "type": "integer", "x-nullable": true }, "allocation_unit": { "type": "string", "enum": [ "percent", "flat" ] }, "assignee_user_ids": { "type": "array", "items": { "type": "integer" }, "x-nullable": true }, "auto_log_time": { "type": "boolean", "x-nullable": true }, "billable": { "type": "boolean", "x-nullable": true }, "color": { "type": "string", "x-nullable": true }, "custom_fields": { "type": "object", "x-nullable": true }, "description": { "type": "string", "x-nullable": true }, "end_date": { "description": "Send together with start_date; must be on or after start_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", "minLength": 1 }, "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 }, "repeat_planned_time_entry_id": { "description": "RepeatPlannedTimeEntryID is the declared initial-selection input that\nwill start a series from an existing planned entry (PR 11). Any\nsupplied value — an ID or JSON null — is rejected until then; the\ncontract is declared in docs/recurring-pr2a-additive-schema.md.\njson.RawMessage keeps absent distinguishable from explicit null on\ndecode and is omitted on marshal when never set.", "type": "integer", "x-nullable": true }, "rollup_enabled": { "type": "boolean" }, "rrule": { "type": "string", "x-nullable": true }, "start_date": { "description": "Send together with end_date; a date without the other is rejected.", "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.PickerChildPage": { "type": "object", "required": [ "data", "eligible_total", "matching_total", "page", "per_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.Task" } }, "eligible_total": { "type": "integer" }, "matching_total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "task.PickerGroup": { "type": "object", "required": [ "eligible_child_count", "first_selectable", "group_id", "matching_child_count", "matching_children_preview", "parent_selectable" ], "properties": { "eligible_child_count": { "type": "integer" }, "first_selectable": { "$ref": "#/definitions/models.Task" }, "group_id": { "type": "integer" }, "matching_child_count": { "type": "integer" }, "matching_children_preview": { "type": "array", "items": { "$ref": "#/definitions/models.Task" } }, "parent": { "$ref": "#/definitions/models.Task" }, "parent_selectable": { "type": "boolean" }, "project": { "$ref": "#/definitions/task.PickerProjectContext" } } }, "task.PickerGroupPage": { "type": "object", "required": [ "data", "eligible_total", "matching_total", "page", "per_page", "project_counts" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/task.PickerGroup" } }, "eligible_total": { "type": "integer" }, "matching_total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "project_counts": { "type": "array", "items": { "$ref": "#/definitions/task.PickerProjectGroupCount" } } } }, "task.PickerProjectContext": { "type": "object", "required": [ "id", "name", "pinned" ], "properties": { "client": { "$ref": "#/definitions/models.ClientLite" }, "color": { "type": "string" }, "end_date": { "type": "string", "format": "date" }, "id": { "type": "integer" }, "name": { "type": "string" }, "pinned": { "type": "boolean" }, "recurring_project_id": { "type": "integer" }, "start_date": { "type": "string", "format": "date" } } }, "task.PickerProjectGroupCount": { "type": "object", "required": [ "eligible_total", "matching_total", "project_id" ], "properties": { "eligible_total": { "type": "integer" }, "matching_total": { "type": "integer" }, "project_id": { "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_entry_total_count", "toggl_user_id", "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", "x-nullable": true }, "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_recurring_series": { "description": "IsRecurringSeries marks a canonical series root (S). Server-owned and\nread-only: no current API path can set it, and the response only exposes\nthe marker while series behavior stays disabled.", "type": "boolean" }, "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_rule": { "description": "The rule of the task's series (RRULE with DTSTART); omitted for a normal task and once the series has stopped.", "type": "string" }, "recurring_series_id": { "description": "The series this task is an occurrence of; omitted for a normal task. Only the server sets it.", "type": "integer" }, "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_entry_total_count": { "type": "integer" }, "toggl_user_id": { "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", "x-nullable": true }, "color": { "type": "string" }, "custom_fields": { "type": "object", "additionalProperties": {} }, "description": { "type": "string" }, "end_date": { "description": "Send together with start_date; must be on or after start_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": { "description": "Send together with end_date; a date without the other is rejected.", "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" } } }, "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" } } } }, "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" }, "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" }, "repeat_time_entry": { "description": "RepeatTimeEntry is the declared composite planned-time repeat input\n(initial selection, PR 11). Any supplied value — true, false or JSON\nnull — is rejected until then; the contract is declared in\ndocs/recurring-pr2a-additive-schema.md. json.RawMessage keeps absent\ndistinguishable from explicit null on decode and is omitted on\nmarshal when never set.", "type": "boolean" }, "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 }, "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" }, "repeat_time_entry": { "description": "RepeatTimeEntry is the declared composite planned-time repeat input\n(initial selection, PR 11), same contract as CreatePayload: any\nsupplied value, including JSON null, is rejected.", "type": "boolean" }, "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 }, "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 }, "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", "maximum": 31536000, "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" }, "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": { "description": "Whether `billable` was set on the entry (`manual`) or resolved from its task, else its project (`task_default`).", "enum": [ "manual", "task_default" ], "allOf": [ { "$ref": "#/definitions/models.BillableSource" } ] }, "calendar_event": { "allOf": [ { "$ref": "#/definitions/timeentry.CalendarEvent" } ], "x-nullable": true }, "calendar_event_id": { "type": "integer" }, "calendar_id": { "description": "CalendarID is the calendar service's calendar PK. It stays set after a calendar deselect clears calendar_event_id.", "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "duration": { "description": "Tracked duration in seconds; omitted while the timer is running and for an entry that is only planned.", "type": "integer" }, "id": { "type": "integer" }, "pattern_generated": { "description": "PatternGenerated is the response-facing derivative of GeneratedByTaskID:\ntrue when the entry was materialized by a series pattern.", "type": "boolean" }, "pattern_managed": { "description": "PatternManaged reports that the pattern engine owns this entry. Server-owned;\npresent in responses, never bindable from a payload.", "type": "boolean" }, "planned_at": { "type": "string", "format": "date-time" }, "planned_duration": { "description": "Planned duration in seconds.", "type": "integer" }, "planned_start": { "description": "Planned start, for time planned on the calendar.", "type": "string", "format": "date-time" }, "project": { "$ref": "#/definitions/models.ProjectLite" }, "project_id": { "type": "integer" }, "start": { "description": "Start of the tracked time; omitted for an entry that is only planned.", "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", "tags" ], "x-enum-varnames": [ "RequiredFieldKindProject", "RequiredFieldKindTask", "RequiredFieldKindDescription", "RequiredFieldKindTags" ] }, "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" }, "time_entry_id": { "description": "Present only when the failing entry is not the one in the request: the running entry that starting a timer would stop.", "type": "integer" } } }, "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" } } } }, "timeentrygroup.timeEntryGroupsResponse": { "type": "object", "required": [ "data", "page", "per_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/models.TimeEntryGroup" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "timeoff.DailyBreakdownEntry": { "type": "object", "required": [ "date", "taken" ], "properties": { "date": { "description": "Date is the day, as an RFC3339 timestamp at 00:00 UTC.", "type": "string" }, "taken": { "description": "Taken is the part of the day taken, from 0 to 1: 1 for a full day, 0.5 for a half day, 0 for a weekend or holiday.", "type": "number" } } }, "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" }, "daily_breakdown": { "description": "DailyBreakdown is the entry's day-by-day count. Omitted when the entry has none.", "type": "array", "items": { "$ref": "#/definitions/timeoff.DailyBreakdownEntry" } }, "days_taken": { "description": "DaysTaken is the entry's day count, the sum of DailyBreakdown. Omitted when zero.", "type": "number" }, "emoji": { "description": "Emoji is the emoji of the entry's time-off policy (category). Omitted from create and update\nresponses and for an entry without a policy.", "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). Omitted from create and update\nresponses and for an entry without a policy.", "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.", "type": "string" }, "time_off_category_id": { "description": "TimeOffCategoryID is the id of the entry's time-off policy (category). Omitted when the entry has no policy.", "type": "integer" }, "timeoff_id": { "description": "ID is the unique identifier of the time off entry.", "type": "integer" }, "type": { "description": "Type is the legacy type enum: vacation, sick, parental or other. Independent of TimeOffCategoryID; omitted when unset.", "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": { "daily_breakdown": { "description": "DailyBreakdown is the entry's day-by-day count: each date within the entry, at most once.\nIts sum is the entry's day count, charged to the member's balance when the entry has a policy.\nOmit it and the entry counts 0 days.", "type": "array", "items": { "$ref": "#/definitions/timeoff.DailyBreakdownEntry" } }, "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" }, "time_off_category_id": { "description": "TimeOffCategoryID is the id of an organization time-off policy (category) to attach.\nIt must belong to the organization; omit to leave the entry without a policy.", "type": "integer" }, "type": { "description": "Type is the optional legacy type enum: vacation, sick, parental or other. Independent of TimeOffCategoryID.", "type": "string", "enum": [ "vacation", "sick", "parental", "other" ] } } }, "timeoff.TimeOffBatchUpdateInput": { "type": "object", "required": [ "end_time", "start_time", "timeoff_id" ], "properties": { "daily_breakdown": { "description": "DailyBreakdown replaces the entry's day-by-day count, with the same rules as on create.\nOmit it to keep the stored one, which must then still fall within the new dates.", "type": "array", "items": { "$ref": "#/definitions/timeoff.DailyBreakdownEntry" } }, "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" }, "time_off_category_id": { "description": "TimeOffCategoryID is the id of an organization time-off policy (category).\nIt must belong to the organization; omit to keep the entry's stored policy.", "type": "integer" }, "timeoff_id": { "description": "ID is the unique identifier of the time off entry to update.", "type": "integer" }, "type": { "description": "Type is the optional legacy type enum: vacation, sick, parental or other. Omitting it clears the stored type; TimeOffCategoryID is unaffected.", "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": { "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.StatusCounts": { "type": "object", "required": [ "approved", "changes_requested", "not_submitted", "submitted" ], "properties": { "approved": { "type": "integer" }, "changes_requested": { "type": "integer" }, "not_submitted": { "type": "integer" }, "submitted": { "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", "monthly" ], "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" } } }, "trackteaminvite.Failure": { "type": "object", "required": [ "code", "organization_user_id" ], "properties": { "code": { "type": "string" }, "organization_user_id": { "type": "integer" } } }, "trackteaminvite.InviteRequest": { "type": "object", "required": [ "organization_user_ids" ], "properties": { "organization_user_ids": { "type": "array", "maxItems": 25, "minItems": 1, "items": { "type": "integer" } } } }, "trackteaminvite.Result": { "type": "object", "required": [ "failed", "invited", "skipped" ], "properties": { "failed": { "type": "array", "items": { "$ref": "#/definitions/trackteaminvite.Failure" } }, "invited": { "type": "array", "items": { "type": "integer" } }, "skipped": { "type": "array", "items": { "type": "integer" } } } }, "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 }, "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" }, "notify_project_alerts": { "type": "boolean" }, "notify_project_member_added": { "type": "boolean" }, "notify_task_assigned": { "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" }, "project_privacy_education_dismissed": { "type": "boolean" }, "reports_guide_dismissed": { "type": "boolean" }, "reports_router_dismissed": { "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" ] }, "task_privacy_education_dismissed": { "type": "boolean" }, "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" }, "timeline_education_dismissed": { "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" }, "work_preparation_reminders_disabled": { "description": "WorkPreparationRemindersDisabled turns off work-preparation reminders for this user in every workspace.", "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": { "$ref": "#/definitions/customfield.Values" } } }, "userworkspace.MergedUserWorkspaceSettings": { "type": "object", "required": [ "approvals_configured", "autolog_time", "has_opened_focus", "is_timesheet_approver", "work_introduction_dismissed" ], "properties": { "active_timesheet_setup_period_days": { "description": "ActiveTimesheetSetupPeriodDays is the period length in days of\nthe caller's setup. Set only for 'days' setups; null for\nweekly/monthly and when the caller is not enrolled.", "type": "integer", "x-nullable": true }, "active_timesheet_setup_periodicity": { "description": "ActiveTimesheetSetupPeriodicity is the periodicity of the setup\nthe caller is enrolled in, or null when they are not a member\nof one.", "enum": [ "weekly", "monthly", "days" ], "allOf": [ { "$ref": "#/definitions/models.Periodicity" } ], "x-nullable": true }, "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" }, "has_opened_focus": { "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" }, "onboarding_intent": { "type": "string", "enum": [ "track", "plan", "projects" ] }, "onboarding_invited_user_ids": { "type": "array", "items": { "type": "integer" } }, "onboarding_project_id": { "type": "integer" }, "onboarding_step": { "type": "string", "enum": [ "team-size", "invite", "calendar", "first-entry", "welcome", "track", "project-sidebar", "project-list", "project-details", "project-estimate", "plan-calendar", "plan-task", "plan-details", "timeline", "capacity", "done" ] }, "onboarding_task_id": { "type": "integer" }, "onboarding_team_size": { "type": "string", "enum": [ "just-me", "2-5", "6-20", "21-50", "50+", "skipped" ] }, "work_introduction_dismissed": { "type": "boolean" } } }, "userworkspace.PartialUpdatePayload": { "type": "object", "properties": { "autolog_time": { "type": "boolean", "x-nullable": true }, "has_opened_focus": { "type": "boolean" }, "onboarding_intent": { "type": "string", "enum": [ "track", "plan", "projects" ] }, "onboarding_invited_user_ids": { "type": "array", "maxItems": 100, "items": { "type": "integer" } }, "onboarding_project_id": { "type": "integer" }, "onboarding_step": { "type": "string", "enum": [ "team-size", "invite", "calendar", "first-entry", "welcome", "track", "project-sidebar", "project-list", "project-details", "project-estimate", "plan-calendar", "plan-task", "plan-details", "timeline", "capacity", "done" ] }, "onboarding_task_id": { "type": "integer" }, "onboarding_team_size": { "type": "string", "enum": [ "just-me", "2-5", "6-20", "21-50", "50+", "skipped" ] }, "work_introduction_dismissed": { "description": "Set true after skipping or accepting the introduction; false does not reset it.", "type": "boolean" } } }, "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 } } }, "workpreparation.Candidate": { "type": "object", "required": [ "email", "name", "user_id" ], "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "user_id": { "type": "integer" } } }, "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", "default_private", "updated_at", "workspace_id" ], "properties": { "created_at": { "type": "string" }, "default_private": { "type": "boolean" }, "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", "properties": { "default_private": { "type": "boolean" }, "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" } } }