Hubstaff App & URL Tracking API

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