API documentation version 1.0

7pace Timetracker for monday.com’s API feature is currently in beta, and we are actively seeking feedback. Please get in touch with support to enable this feature.

On this page:

1 About this API
2 Contact
3 Create an API token
4 Authentication
5 API conventions
- 5.1 Worklog fields
  - 5.1.1 ID
  - 5.1.2 Duration
  - 5.1.3 Comment
  - 5.1.4 ExternalItemId
  - 5.1.5 User Identifiers
  - 5.1.6 Date Fields
- 5.2 Passing Arrays in Queries
6 Error handling
- 6.1 Examples
7 Rate limiting
8 Endpoints
- 8.1 Worklogs
- 8.2 Query parameters
- 8.3 Settings: Custom fields
9 Future enhancements
10 Swagger

On this page:

1 About this API
2 Contact
3 Create an API token
4 Authentication
5 API conventions
- 5.1 Worklog fields
  - 5.1.1 ID
  - 5.1.2 Duration
  - 5.1.3 Comment
  - 5.1.4 ExternalItemId
  - 5.1.5 User Identifiers
  - 5.1.6 Date Fields
- 5.2 Passing Arrays in Queries
6 Error handling
- 6.1 Examples
7 Rate limiting
8 Endpoints
- 8.1 Worklogs
- 8.2 Query parameters
- 8.3 Settings: Custom fields
9 Future enhancements
10 Swagger

About this API

Welcome to the documentation for the 7pace Reporting REST API, version 1.0.
This API enables secure and efficient access to your 7pace worklog data and account custom field settings.

Obtain OpenAPI Specification from the Swagger section below.

Contact

If you require assistance, please contact our support team using the Support Portal.

Create an API token

The API requires JWT Bearer Token authentication. Use the following steps to create a new token:

Navigate to 7pace Timetracker Settings, click > API Tokens.
Click + Create token.
Name the token and set an expiration date.
Click Create.
Copy the API token and save it.

Authentication

Include your token in the Authorization header of each request.

Example:

curl https://timehubmdy.7pace.com/api/v1/worklogs --header 'Authorization: Bearer YOUR_TOKEN'

API conventions

Worklog fields

ID

Unique, persistent identifier of the worklog.
It will not change over time once created.

Duration

Total time recorded for the worklog in seconds.

Comment

Optional text entered by the user, typically describing the work performed.

ExternalItemId

Internal, immutable monday.com item ID associated with the worklog.

User Identifiers

Each worklog references users through different roles, each represented by a unique monday.com user ID:

AuthorId: User who originally created the worklog.
EditorId: User who last edited the worklog.
AssigneeId: User who this worklog belongs to.

Date Fields

StartedAt:
The local datetime when the user started the work being logged.
Format: DateTime (local, no timezone).
CreatedAt:
The UTC datetime when the worklog entry was originally created in the system.
Format: DateTimeOffset (UTC).
EditedAt:
The UTC datetime when the worklog was last modified (for example, edited comment, changed duration).
Format: DateTimeOffset (UTC).

Passing Arrays in Queries

When passing arrays (e.g., authorId, assigneeId, externalItemId), use comma-separated values:

GET /worklogs?authorId=1,2,3,4

No need to repeat the parameter. The server automatically splits the values based on commas.

Error handling

General Errors:
- Title: INTERNAL_ERROR
- Status: 500
- Detail: Exception message.
- Trace ID included (traceId) for debugging.
Timeout Errors:
- Title: BAD_REQUEST
- Status: 400
- Special handling for timeouts.
GraphQL Errors:
- Title: BAD_REQUEST
- Status: 400
- Detail: Single or multiple API error messages.
- Special handling for timeouts.
Validation Errors:
- Title: VALIDATION_ERROR
- Status: 400
- Detail: “One or more validation errors occurred. Check your input parameters.”

Examples

{
    "title": "VALIDATION_ERROR",
    "status": 400,
    "detail": "One or more validation errors occurred. Check your input parameters.",
    "errors": {
        "queryValues": [
            "Unsupported query value for key 'createdAt.end': 'Provided value '123' is not a valid date.'"
        ],
        "queryParameters": [
            "Unexpected query parameters: createdAt.stat"
        ]
    },
    "traceId": "00-163698a761739c0c-01"
}

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "Your request takes too long, try to simplify it or try again later.",
  "traceId": "00-abc123def456-xyz789-01"
}

{
  "title": "INTERNAL_ERROR",
  "status": 500,
  "detail": "Unexpected error occurred.",
  "traceId": "00-abc123def456-xyz789-01"
}

Rate limiting

The 7pace Reporting API applies dynamic rate limiting to ensure service stability. If rate limits are exceeded, requests will be throttled and a 429 Too Many Requests status will be returned. Clients are advised to implement exponential backoff or retry logic as needed.

Endpoints

Worklogs

GET /worklogs

Retrieve a paginated list of worklogs with optional filtering criteria.

Query parameters

Name	Type	Description

Name	Type	Description
before	string	Cursor for pagination. Returns results before the specified cursor.
after	string	Cursor for pagination. Returns results after the specified cursor.
externalItemId	array of strings	Filter by external item IDs
assigneeId	array of strings	Filter by assignee IDs
authorId	array of strings	Filter by author IDs
startedAt.start	datetime	Start of worklog date range
startedAt.end	datetime	End of worklog date range
editedAt.start	datetime	Start of edit date range
editedAt.end	datetime	End of edit date range
createdAt.start	datetime	Start of create date range
createdAt.end	datetime	End of create date range

Response (200 OK)

{
    "result": [ /* array of worklogs */ ],
    "_links": {
        "self": {"href": "..."},
        "prev": {"href": "..."},
        "next": {"href": "..."}
    },
    "pageInfo": {
        "hasNextPage": true,
        "hasPreviousPage": false
    }
}

Settings: Custom fields

GET /settings/customFields

Custom field settings describe available fields for your account, such as toggles and dropdowns.
Worklogs (from /worklogs) only store field IDs and their values.
To reconstruct the full custom field information, you need to:

Fetch the settings once.
When reading a worklog, match customFields.toggle.id or customFields.dropdown.id against the list from /settings/customFields.
This lets you display the field’s name, value, and type correctly.

Response (200 OK)

{
    "result": {
        "dropdown": [...],
        "toggle": [...]
    }
}

Future enhancements

Planned API enhancements include:

Custom fields.
Filtering options.
The ability to request specific fields.
CRUD operations.

Swagger

Swagger can be inserted here to visualize:

openapi: 3.0.0
info:
  title: 7pace REST API
  description: API to fetch worklogs and account settings.
  version: 1.0.0

servers:
  - url: <https://timehubmdy.7pace.com/api/v1>
    description: Production API

paths:
  /api/v1/worklogs:
    get:
      summary: Get a list of worklogs
      description: Returns a paginated list of worklogs with filters.
      parameters:
        - name: before
          in: query
          schema:
            type: string
          description: Cursor for pagination. Returns results before the specified cursor.
        - name: after
          in: query
          schema:
            type: string
          description: Cursor for pagination. Returns results after the specified cursor.
        - name: externalItemId
          in: query
          schema:
            type: array
            items:
              type: string
          description: Accepts a single string or array.
        - name: assigneeId
          in: query
          schema:
            type: array
            items:
              type: string
          description: Accepts a single string or array.
        - name: authorId
          in: query
          schema:
            type: array
            items:
              type: string
          description: Accepts a single string or array.
        - name: startedAt.start
          in: query
          schema:
            type: string
            format: date-time
          description: Start date filter.
        - name: startedAt.end
          in: query
          schema:
            type: string
            format: date-time
          description: End date filter.
        - name: editedAt.start
          in: query
          schema:
            type: string
            format: date-time
          description: Start edit date filter.
        - name: editedAt.end
          in: query
          schema:
            type: string
            format: date-time
          description: End edit date filter.
        - name: createdAt.start
          in: query
          schema:
            type: string
            format: date-time
          description: Start creation date filter.
        - name: createdAt.end
          in: query
          schema:
            type: string
            format: date-time
          description: End creation date filter.
      responses:
        "200":
          description: A list of worklogs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: "#/components/schemas/Worklog"
                  _links:
                    type: object
                    properties:
                      self:
                        type: object
                        properties:
                          href:
                            type: string
                      prev:
                        type: object
                        properties:
                          href:
                            type: string
                      next:
                        type: object
                        properties:
                          href:
                            type: string
                  pageInfo:
                    $ref: "#/components/schemas/PageInfo"
        "400":
          description: Error response for invalid filters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  detail:
                    type: string
                  traceId:
                    type: string
    post:
      summary: Create a worklog
      description: Creates a worklog by its Id.
      requestBody:
        description: Worklog object to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorklogRequest"
      responses:
        "200":
          description: Worklog created successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorklogResponse"
        "400":
          description: Worklog cannot be created. This could be for a number of reasons, including invalid request body, or the submitting user does not have permission to update that worklog.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        "401":
          description: Unauthorized access. This indicates a problem with Authorization. Ensure apitoken is valid, and you are setting Authorization header to Bearer {apitoken}
        "500":
          description: Internal server error.

  /api/v1/settings/customFields:
    get:
      summary: Get account settings
      description: Returns the custom fields settings for the current account.
      responses:
        "200":
          description: Account settings data
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      customFields:
                        type: object
                        $ref: "#/components/schemas/AccountSettings"

  /api/v1/worklogs/{worklogId}:
    delete:
      summary: Delete a worklog
      description: Deletes a worklog by its ID.
      parameters:
        - name: worklogId
          in: path
          required: true
          schema:
            type: string
          description: The ID of the worklog to delete.
      responses:
        "204":
          description: Worklog deleted successfully.
        "400":
          description: Worklog cannot be deleted. This could be for a number of reasons, including passed worklog ID is invalid, worklog has already been deleted, or the submitting user does not have permission to delete that worklog.
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                  detail:
                    type: string
                  traceId:
                    type: string
                  exception:
                    type: object
                    properties:
                      details:
                        type: string
                      headers:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      path:
                        type: string
                      endpoint:
                        type: string
                        nullable: true
                      routeValues:
                        type: object
        "401":
          description: Unauthorized access. This indicates a problem with Authorization. Ensure apitoken is valid, and you are setting Authorization header to Bearer {apitoken}
    put:
      summary: Update a worklog
      description: Updates a worklog by its Id.
      parameters:
        - name: worklogId
          in: path
          required: true
          schema:
            type: string
          description: The Id of the worklog to update.
      requestBody:
        description: Worklog object to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorklogRequest"
      responses:
        "200":
          description: Worklog updated successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorklogResponse"
        "400":
          description: Worklog cannot be updated. This could be for a number of reasons, including passed worklog ID is invalid, invalid request body, or the submitting user does not have permission to update that worklog.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        "401":
          description: Unauthorized access. This indicates a problem with Authorization. Ensure apitoken is valid, and you are setting Authorization header to Bearer {apitoken}
        "500":
          description: Internal server error.

security:
  - bearer: []

components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

  schemas:
    PageInfo:
      type: object
      properties:
        hasNextPage:
          type: boolean
        hasPreviousPage:
          type: boolean
        startCursor:
          type: string
        endCursor:
          type: string

    Worklog:
      type: object
      properties:
        id:
          type: string
          format: uuid
        comment:
          type: string
        startedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        editedAt:
          type: string
          format: date-time
        assigneeId:
          type: string
        authorId:
          type: string
        accountId:
          type: string
        editorId:
          type: string
        duration:
          type: integer
        externalItemId:
          type: string
        customFields:
          $ref: "#/components/schemas/CustomFields"

    WorklogResponse:
      type: object
      properties:
        worklog:
          $ref: "#/components/schemas/Worklog"

    WorklogRequest:
      type: object
      properties:
        comment:
          type: string
        startedAt:
          type: string
          format: date-time
          description: Date and time of starting work in the format YYYY-MM-DDTHH:mm:ss or YYYY-MM-DDTHH:mm:ss±hh:mm. Timezone offset is ignored.
        assigneeId:
          type: string
        duration:
          type: integer
        externalItemId:
          type: string
        customFields:
          $ref: "#/components/schemas/CustomFields"

    CustomFields:
      type: object
      properties:
        toggle:
          type: array
          items:
            $ref: "#/components/schemas/ToggleField"
        dropdown:
          type: array
          items:
            $ref: "#/components/schemas/DropdownField"

    ToggleField:
      type: object
      properties:
        id:
          type: string
        value:
          type: boolean

    DropdownField:
      type: object
      properties:
        id:
          type: string
        value:
          type: array
          items:
            type: string

    AccountSettings:
      type: object
      properties:
        dropdown:
          type: array
          items:
            $ref: "#/components/schemas/DropdownSettings"
        toggle:
          type: array
          items:
            $ref: "#/components/schemas/ToggleSettings"

    DropdownSettings:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        enabled:
          type: boolean
        mandatory:
          type: boolean
        description:
          type: string
        options:
          type: array
          items:
            $ref: "#/components/schemas/DropdownOptionSettings"

    DropdownOptionSettings:
      type: object
      properties:
        id:
          type: string
        value:
          type: string
        color:
          type: string
        used:
          type: integer

    ToggleSettings:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        enabled:
          type: boolean
        mandatory:
          type: boolean
        description:
          type: string
        default:
          type: boolean