Hourtick Integrations API

openapi: 3.2.0
info:
  title: Hourtick Integrations API
  version: 1.0.0
  description: 'The Hourtick REST API. Authenticate with a personal API token: create one in **Settings → API tokens**, then send `Authorization: Bearer ht_…`.


    All timer changes go through **POST /api/v1/commands**, the same endpoint the web and Mac apps use. Commands are idempotent per `commandId` (use a new UUID per action, reuse it to retry safely).


    Every response carries a `Server-Time` header (epoch ms). Errors use RFC 9457 problem details.'
servers:
- url: https://hourtick.com
security:
- bearer: []
tags:
- name: Integrations
  description: Your own accounts in Linear, Notion, Teamwork and Asana. Connecting needs a person's browser (OAuth); AI agents can't connect or link, and never post through a person's connection. Tokens are stored encrypted and never returned.
paths:
  /api/v1/integrations:
    get:
      tags:
      - Integrations
      summary: 'Linear, Notion, Teamwork and Asana: whether each is available and whether you…'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: '{ integrations: [{ id, label, available, asks, connection: { accountName, connectedAt } | null }] }'
        '401':
          description: Missing or invalid token
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      operationId: getApiV1Integrations
      x-operation-id-source: derived
  /api/v1/integrations/{provider}:
    post:
      tags:
      - Integrations
      summary: 'Start connecting: returns the vendor''s approval address to open in a browser'
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          enum:
          - linear
          - notion
          - teamwork
          - asana
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
        '403':
          description: AI agents can't connect accounts
        '404':
          description: Unknown or not set up on this server
      operationId: postApiV1IntegrationsByProvider
      x-operation-id-source: derived
    delete:
      tags:
      - Integrations
      summary: 'Disconnect: forgets the tokens and asks the vendor to revoke them where it…'
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          enum:
          - linear
          - notion
          - teamwork
          - asana
      responses:
        '204':
          description: Disconnected
      operationId: deleteApiV1IntegrationsByProvider
      x-operation-id-source: derived
  /api/v1/work-items/{id}/links:
    get:
      tags:
      - Integrations
      summary: Items linked to a task, with their current title and status (re-read when older…
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: '{ links: [{ id, provider, label, url, title, status }] }'
        '404':
          description: No such task
      operationId: getApiV1WorkItemsByIdLinks
      x-operation-id-source: derived
    post:
      tags:
      - Integrations
      summary: Link a Linear issue, Notion page, Teamwork task or Asana task by its address
      description: 'The provider is recognised from the address (a Linear identifier such as `ENG-123` also works). You must be connected to it first (409 otherwise). One link per provider per task: a new one replaces the old. Time tracked on a Teamwork-linked task is sent to Teamwork; Linear, Notion and Asana get one comment with the total when the task is done.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: '{ link }'
        '403':
          description: AI agents can't link
        '409':
          description: Not connected to that provider
        '422':
          description: Invalid request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      operationId: postApiV1WorkItemsByIdLinks
      x-operation-id-source: derived
  /api/v1/work-items/{id}/links/{linkId}:
    delete:
      tags:
      - Integrations
      summary: Remove a link. Time already sent to Teamwork stays there
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: linkId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Removed
      operationId: deleteApiV1WorkItemsByIdLinksByLinkId
      x-operation-id-source: derived
components:
  schemas:
    Problem:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        entry:
          $ref: '#/components/schemas/TimeEntry'
        conflicts:
          type: array
          description: 'Bulk edits: entries that blocked the change.'
          items:
            type: object
            properties:
              id:
                type: string
              reason:
                type: string
    TimeEntry:
      type: object
      properties:
        id:
          type: string
          format: uuid
        workspaceId:
          type: string
          format: uuid
        userId:
          type: string
        projectId:
          type: string
          format: uuid
        taskId:
          type: string
          format: uuid
          description: Task type
        workItemId:
          type:
          - string
          - 'null'
          format: uuid
          description: The task this time is for, if any
        notes:
          type: string
        spentDate:
          type: string
          format: date
          description: The day the time belongs to (user's time zone).
        timezone:
          type: string
          examples:
          - Europe/Copenhagen
        accumulatedSeconds:
          type: integer
          description: Seconds banked from completed runs.
        timerStartedAt:
          type:
          - integer
          - 'null'
          description: Epoch ms when the current run started; null when stopped.
        billable:
          type: boolean
        lockedReason:
          type:
          - string
          - 'null'
          enum:
          - null
          - invoiced
          - approved
          - submitted
        version:
          type: integer
        deletedAt:
          type:
          - integer
          - 'null'
        createdAt:
          type: integer
        updatedAt:
          type: integer
      description: Live duration = accumulatedSeconds + (now − timerStartedAt)/1000 while running.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: ht_… personal API token