Timeular Time Entries API

openapi: 3.0.3
info:
  title: EARLY (Timeular) Public Activities Time Entries API
  version: v4
  description: Public REST API for EARLY (formerly Timeular) time tracking. Manage activities, time entries, live tracking, tags & mentions, folders, users, leaves, and webhook subscriptions. Authentication is via API Key + API Secret exchanged for a Bearer Access Token. Derived by API Evangelist from the provider-published public Postman collection.
  contact:
    name: EARLY Developer Support
    url: https://developers.early.app/
  x-derived-from: https://developers.early.app/ public Postman collection T1DwdEke
servers:
- url: https://api.early.app/api/v4
  description: Production (V4 - current)
security:
- bearerAuth: []
tags:
- name: Time Entries
paths:
  /api/v4/time-entries/{timestamp}/{timestamp}:
    get:
      summary: Find Time Entries in given range
      operationId: findTimeEntriesInGivenRange
      tags:
      - Time Entries
      description: Find Time Entries within the given time range.
      parameters:
      - name: timestamp
        in: path
        required: true
        schema:
          type: string
      - name: timestamp
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                timeEntries:
                - id: '1'
                  activity:
                    id: '1'
                    name: abc
                    color: '#000000'
                    folderId: '1'
                  duration:
                    startedAt: '2020-01-01T00:00:00.000'
                    stoppedAt: '2020-01-01T01:00:00.000'
                  note:
                    text: If there is a possibility of several things going wrong, the one that will cause the most damage will be the one to go wrong <{{|t|2|}}><{{|t|1|}}><{{|m|1|}}><{{|m|2|}}>
                    tags:
                    - id: 1
                      key: 43d10bff-65c6-4aab-879e-8e4b9106c99d
                      label: burst
                      scope: timeular
                      folderId: '1'
                    - id: 2
                      key: 849ab930-4492-4b73-b378-8bff6d12fdd0
                      label: interpret
                      scope: timeular
                      folderId: '1'
                    mentions:
                    - id: 1
                      key: 8ed8ca39-813b-4f9d-a1ba-9a18b6c001e0
                      label: Joanie
                      scope: timeular
                      folderId: '1'
                    - id: 2
                      key: 999f14a2-c0d2-430a-b1c0-23495f96b1cb
                      label: Violette
                      scope: timeular
                      folderId: '1'
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                error:
                  message: Explanation of what has happened
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error:
                  message: Explanation of what has happened
  /api/v4/time-entries:
    post:
      summary: Create Time Entry
      operationId: createTimeEntry
      tags:
      - Time Entries
      description: 'With this endpoint, you can create a new Time Entry. It should be connected to an Activity and have a duration no shorter than 1 minute. A Note can be provided too, but it’s not required. Within this Note, you can refer one or more Tags or Mentions.

        These Tags and Mentions need to be referenced by their ID and put inside a special prefix and suffix, &lt;{{|t|1|}}&gt; for the tag with id 1 and &lt;{{|m|1|}}&gt; for the mention with id 1.

        If the related Activity is bound to some Integration, let’s say a JIRA Project, JIRA task IDs is a valid Mention. The Time Entry will be created even if it overlaps with other Time Entries – in result existing Time Entries will be split or deleted in such manner, that new one will fit without overlapping.'
      requestBody:
        required: true
        content:
          application/json:
            example:
              activityId: '1'
              startedAt: '2016-08-05T06:00:00.000'
              stoppedAt: '2016-08-05T07:00:00.000'
              note:
                text: 99 sheep <{{|t|1|}}> <{{|m|1|}}>
      responses:
        '201':
          description: Created Time Entry
          content:
            application/json:
              example:
                id: '1'
                activity:
                  id: '1'
                  name: abc
                  color: '#000000'
                  folderId: '1'
                duration:
                  startedAt: '2016-08-05T06:00:00.000'
                  stoppedAt: '2016-08-05T07:00:00.000'
                note:
                  text: 99 sheep <{{|t|1|}}><{{|m|1|}}>
                  tags:
                  - id: 1
                    key: dabf59bc-9997-44ca-9451-e753a11090c4
                    label: some-tag
                    scope: timeular
                    folderId: '1'
                  mentions:
                  - id: 1
                    key: debf59bc-9997-44ca-9451-e753a11090c4
                    label: some mention
                    scope: timeular
                    folderId: '1'
                errors: []
        '500':
          description: Integration-related error, eg. if new Time Entry somehow conflicts with data on the Integration side
          content:
            application/json:
              example:
                error:
                  message: Explanation of what has happened
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error:
                  message: Explanation of what has happened
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                error:
                  message: Explanation of what has happened
        '404':
          description: Activity not found
          content:
            application/json:
              example:
                error:
                  message: Explanation of what has happened
  /api/v4/time-entries/{id}:
    get:
      summary: Find Time Entry by its ID
      operationId: findTimeEntryByItsId
      tags:
      - Time Entries
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Found Time Entry
          content:
            application/json:
              example:
                id: '3'
                activity:
                  id: '1'
                  name: abc
                  color: '#000000'
                  folderId: '1'
                duration:
                  startedAt: '2016-08-05T06:00:00.000'
                  stoppedAt: '2016-08-05T07:00:00.000'
                note:
                  text: 99 sheep <{{|t|1|}}><{{|m|1|}}>
                  tags:
                  - id: 1
                    key: dabf59bc-9997-44ca-9451-e753a11090c4
                    label: some-tag
                    scope: timeular
                    folderId: '1'
                  mentions:
                  - id: 1
                    key: debf59bc-9997-44ca-9451-e753a11090c4
                    label: some mention
                    scope: timeular
                    folderId: '1'
                errors: []
        '404':
          description: Time Entry not found
          content:
            application/json:
              example:
                error:
                  message: Explanation of what has happened
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error:
                  message: Explanation of what has happened
    patch:
      summary: Edit a Time Entry
      operationId: editATimeEntry
      tags:
      - Time Entries
      description: 'With this endpoint you can edit an existing time entry. When changing the activity ID please note, that both the new and old activity attached to time entry have to belong to same integration.

        To remove a note, just set the complete object to null and all values within the object will be deleted too.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            example:
              activityId: '1'
              startedAt: '2016-08-05T06:01:00.000'
              stoppedAt: '2016-08-05T07:01:00.000'
              note:
                text: 200 sheep <{{|t|1|}}> <{{|m|1|}}>
      responses:
        '200':
          description: Edited Time Entry
          content:
            application/json:
              example:
                id: '1'
                activity:
                  id: '1'
                  name: abc
                  color: '#000000'
                  folderId: '1'
                duration:
                  startedAt: '2016-08-05T06:00:00.000'
                  stoppedAt: '2016-08-05T07:00:00.000'
                note:
                  text: 200 sheep <{{|t|1|}}><{{|m|1|}}>
                  tags:
                  - id: 1
                    key: dabf59bc-9997-44ca-9451-e753a11090c4
                    label: some-tag
                    scope: timeular
                    folderId: '1'
                  mentions:
                  - id: 1
                    key: debf59bc-9997-44ca-9451-e753a11090c4
                    label: some mention
                    scope: timeular
                    folderId: '1'
                errors: []
        '404':
          description: Activity or Time Entry not found
          content:
            application/json:
              example:
                error:
                  message: Explanation of what has happened
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                error:
                  message: Explanation of what has happened
        '500':
          description: Integration-related error, eg. if given integration does not exist
          content:
            application/json:
              example:
                error:
                  message: Explanation of what has happened
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error:
                  message: Explanation of what has happened
    delete:
      summary: Delete a Time Entry
      operationId: deleteATimeEntry
      tags:
      - Time Entries
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                errors:
                - Any error which can be ignored and did not prevented action to be performed successfully.
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                error:
                  message: Explanation of what has happened
        '404':
          description: Time Entry not found
          content:
            application/json:
              example:
                error:
                  message: Explanation of what has happened
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error:
                  message: Explanation of what has happened
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Access Token obtained from POST /developer/sign-in using your API Key and API Secret.