openapi: 3.0.3 info: title: Hubstaff Activities App & URL Tracking API description: 'The Hubstaff API v2 provides programmatic read and write access to Hubstaff''s time tracking, timesheet, workforce management, and project management data - organizations, members, teams, projects, tasks, clients, activities (10-minute tracked time blocks with activity percentages), daily activity aggregates, time entries, timesheets and approvals, time off requests/policies/balances, attendance schedules and shifts, screenshots, app and URL usage, invoices, team payments, and webhooks. Authentication uses OpenID Connect / OAuth 2.0 through Hubstaff Account (https://account.hubstaff.com). For server-side scripts, create a personal access token at https://developer.hubstaff.com/personal_access_tokens - the PAT acts as an OAuth refresh token (90-day expiry) that you exchange for short-lived access tokens at https://account.hubstaff.com/access_tokens. Send the access token as a Bearer token on every request. Rate limit: authenticated users are allowed 1,000 requests per hour per application; individual requests time out after 30 seconds. All requests must use HTTPS. Collection endpoints use cursor pagination via page_start_id and page_limit. This document is a curated OpenAPI 3.0 rendering of the live Swagger 2.0 definition published at https://api.hubstaff.com/v2/docs, covering the primary resource areas; consult the live definition for the complete surface (insights, job sites, budgets, overtime policies, integrations, and more).' version: '2.0' contact: name: Hubstaff Developer Portal url: https://developer.hubstaff.com/ termsOfService: https://hubstaff.com/terms servers: - url: https://api.hubstaff.com description: Hubstaff production API (paths include the /v2 prefix) security: - oauth2: - hubstaff:read - personalAccessToken: [] tags: - name: App & URL Tracking description: Application and URL usage captured while tracking, plus tracking settings. paths: /v2/organizations/{organization_id}/tool_usages: get: operationId: getV2OrganizationsOrganizationIdToolUsages tags: - App & URL Tracking summary: List organization tool usages description: 'Returns a collection of tool usages (productivity tool usage) for the given organization. Results can be filtered by time_slot[start]/[stop], user_ids[], task_ids[], project_ids[], and tool_type. The preferred endpoints to fetch tool usage data are the daily endpoints. Requires Owner or Organization Manager role (with view others data permission). Note: Date range limit is 7 days. Earliest date is 1 month ago.' parameters: - name: organization_id in: path required: true schema: type: integer format: int32 - name: page_start_id in: query description: The page start ID. schema: type: integer format: int32 default: 0 - name: page_limit in: query description: The default page size schema: type: integer format: int32 default: null - name: time_slot[start] in: query description: Start time (ISO 8601) required: true schema: type: string format: date-time - name: time_slot[stop] in: query description: Stop time (ISO 8601, Exclusive) required: true schema: type: string format: date-time - name: user_ids in: query description: List of user IDs schema: type: array items: type: integer format: int32 - name: task_ids in: query description: List of task IDs schema: type: array items: type: integer format: int32 - name: project_ids in: query description: List of project IDs schema: type: array items: type: integer format: int32 - name: tool_type in: query description: Filter by tool type (application or url) schema: type: string enum: - application - url - name: include in: query description: Specify related data to side load. schema: type: array items: type: string enum: - users - projects - tasks responses: '200': description: A list of tool usages '400': description: Invalid parameters '401': description: Unauthorized '403': description: API access is only for organizations on an active plan '404': description: Could not find record '429': description: Rate limit exceeded /v2/organizations/{organization_id}/tool_usages/daily: get: operationId: getV2OrganizationsOrganizationIdToolUsagesDaily tags: - App & URL Tracking summary: List organization daily tool usages description: 'Returns daily aggregated time spent using productivity tools (apps and websites categorized by Hubstaff). Results can be filtered by user_ids[], task_ids[], project_ids[], tool_type, and date[start]/[stop]. Requires Owner or Organization Manager role (with view others data permission). Note: Date range limit is 14 days. Earliest date is 1 month ago.' parameters: - name: organization_id in: path required: true schema: type: integer format: int32 - name: page_start_id in: query description: The page start ID. schema: type: integer format: int32 default: 0 - name: page_limit in: query description: The default page size schema: type: integer format: int32 default: null - name: date[start] in: query description: Start date (ISO 8601) required: true schema: type: string format: date - name: date[stop] in: query description: Stop date (ISO 8601, Inclusive) required: true schema: type: string format: date - name: user_ids in: query description: List of user IDs schema: type: array items: type: integer format: int32 - name: task_ids in: query description: List of task IDs schema: type: array items: type: integer format: int32 - name: project_ids in: query description: List of project IDs schema: type: array items: type: integer format: int32 - name: tool_type in: query description: Filter by tool type (application or url) schema: type: string enum: - application - url - name: include in: query description: Specify related data to side load. schema: type: array items: type: string enum: - users - projects - tasks responses: '200': description: A list of daily tool usages '400': description: Invalid parameters '401': description: Unauthorized '403': description: API access is only for organizations on an active plan '404': description: Could not find record '429': description: Rate limit exceeded /v2/organizations/{organization_id}/app_and_url_tracking_settings: get: operationId: getV2OrganizationsOrganizationIdAppAndUrlTrackingSettings tags: - App & URL Tracking summary: List member Track Apps & URLs settings description: 'Returns the Track Apps & URLs setting for the organization''s members. Results can be filtered to specific members with `user_ids`. When no filter is given, all members are returned. Only organization Owners and Managers may use this endpoint.' parameters: - name: organization_id in: path required: true schema: type: integer format: int32 - name: page_start_id in: query description: The page start ID. schema: type: integer format: int32 default: 0 - name: page_limit in: query description: The default page size schema: type: integer format: int32 default: null - name: user_ids in: query description: List of user IDs schema: type: array items: type: integer format: int32 - name: include in: query description: Specify related data to side load. schema: type: array items: type: string enum: - users responses: '200': description: A list of member Track Apps & URLs settings '400': description: Invalid parameters '401': description: Unauthorized '403': description: API access is only for organizations on an active plan '404': description: Could not find record '429': description: Rate limit exceeded put: operationId: putV2OrganizationsOrganizationIdAppAndUrlTrackingSettings tags: - App & URL Tracking summary: Update member Track Apps & URLs settings description: 'Sets the Track Apps & URLs setting for the organization''s members. Allowed values: `off`, `apps`, `apps_and_urls`. Available only to organizations whose plan includes Apps & URLs tracking. Provide `user_ids` to update specific members. To change the organization-wide default instead — which cascades to every current and future member — set `apply_to_all_members` to `true` and omit `user_ids`. The organization-wide change is cautionary and irreversible in bulk: the response reports `scope: "global"`, and for large organizations it is applied in the background. `user_ids` and `apply_to_all_members` are mutually exclusive, and exactly one of them must be given (this prevents an accidental org-wide change when filters are omitted). When targeting `user_ids`, omit `apply_to_all_members` entirely — sending it as `false` is rejected. Only organization Owners and Managers may use this endpoint.' parameters: - name: organization_id in: path required: true schema: type: integer format: int32 requestBody: required: true content: application/json: schema: type: object description: Request payload. See the live Hubstaff API reference (https://api.hubstaff.com/v2/docs) for the full schema. responses: '200': description: Update result '400': description: Invalid parameters '401': description: Unauthorized '403': description: API access is only for organizations on an active plan '404': description: Could not find record '429': description: Rate limit exceeded components: securitySchemes: oauth2: type: oauth2 description: Hubstaff Account OpenID Connect / OAuth 2.0 authentication. Scopes are hubstaff:read and hubstaff:write. flows: authorizationCode: authorizationUrl: https://account.hubstaff.com/authorizations/new tokenUrl: https://account.hubstaff.com/access_tokens scopes: hubstaff:read: Read access to the Hubstaff API hubstaff:write: Write access to the Hubstaff API personalAccessToken: type: http scheme: bearer description: Access token obtained by exchanging a personal access token (created at https://developer.hubstaff.com/personal_access_tokens) via the OAuth 2.0 refresh token grant at https://account.hubstaff.com/access_tokens. PATs expire after 90 days. externalDocs: description: Hubstaff API v2 reference (interactive) url: https://developer.hubstaff.com/docs/hubstaff_v2