Home Companion apps Building with the Timether API

Building with the Timether API

Last updated on May 26, 2026

The Timether API lets developers connect workspace data with internal tools, dashboards, reporting systems, automations, and custom workflows.

API access is available for Team and Business workspaces through public API tokens.

For comprehensive API documents, visit https://api-docs.timether.com

API availability

Public API access is available on:

  • Team

  • Business

API token access is not available on the Free or Solo Pro plans.

If you do not see API token settings in your workspace, check that your workspace is on a supported plan and that your role has permission to access developer settings.

Creating an API token

To create an API token:

  1. Go to Workspace Settings.

  2. Open the Developer, API, or API Tokens section.

  3. Click Create Token.

  4. Give the token a clear name.

  5. Copy the generated token and store it securely.

API tokens are shown only once when they are created.

If you lose the token, you will need to revoke it and create a new one.

Making API requests

Timether API requests use the base path:

/api/v1

Each API request should include the API token in the Authorization header using the Bearer format.

Example:

Authorization: Bearer your_api_token_here

You must also include the workspace context using the X-Workspace-Id header.

Example:

X-Workspace-Id: your_workspace_id_here

A typical request should include:

Authorization: Bearer your_api_token_here
X-Workspace-Id: your_workspace_id_here
Content-Type: application/json

Workspace headers are required

Timether accounts can belong to multiple workspaces, and each workspace has its own separate data.

Because of this, API requests must include the X-Workspace-Id header.

This tells Timether which workspace the request should operate inside.

If the workspace ID is missing, invalid, or not available to the token’s user, the request may be rejected.

Strict workspace scoping

API requests are strictly scoped to the workspace provided in the X-Workspace-Id header.

This means API requests can only access records that belong to that workspace.

For example:

  • You cannot create a time entry for a project from another workspace.

  • You cannot associate a project with a client from another workspace.

  • You cannot update a timer using a project outside the active workspace.

  • You cannot fetch workspace records from a different workspace using the wrong workspace ID.

These rules help prevent accidental data leaks, incorrect reporting, and cross-workspace billing mistakes.

If an API request references a project, client, tag, timer, or time entry from another workspace, Timether will block the request.

Workspace membership fields

Workspace membership objects may include planning and cost fields for team management.

These fields are:

{
  "expected_weekly_capacity_hours": 40,
  "internal_hourly_cost_cents": 3500
}

expected_weekly_capacity_hours

expected_weekly_capacity_hours stores the number of hours a workspace member is expected to work in a typical week.

For example:

{
  "expected_weekly_capacity_hours": 40
}

This value can be used for capacity utilization reporting.

For example, if a member tracks 32 hours in a week and their expected weekly capacity is 40 hours, their utilization is 80%.

internal_hourly_cost_cents

internal_hourly_cost_cents stores the internal hourly cost of a workspace member in integer cents.

For example, an internal cost of $35.00/hour is stored as:

{
  "internal_hourly_cost_cents": 3500
}

Using integer cents helps avoid rounding issues in cost and profitability calculations.

This value is used for internal reporting, such as billable vs. non-billable cost breakdowns and project profit margin calculations.

Access restrictions for member planning fields

The expected_weekly_capacity_hours and internal_hourly_cost_cents fields are restricted to Owner and Manager roles.

Regular Members and Viewers cannot view or manage these values.

This is because capacity and internal cost data may include sensitive business information.

If an API token is used by a user who does not have permission to access these fields, Timether may hide the fields or reject attempts to update them.

Updating member capacity and internal cost

Owners and Managers can update member planning fields through supported workspace membership endpoints.

When updating these values, send the new values as part of the membership update request.

Example request body:

{
  "expected_weekly_capacity_hours": 40,
  "internal_hourly_cost_cents": 3500
}

Use clear internal rules for these values so reporting stays consistent across the workspace.

For example, decide whether internal hourly cost should represent salary cost, contractor cost, blended cost, or another internal accounting method.

Internal cost snapshot behavior

When a time entry is created, Timether snapshots the member’s current internal hourly cost onto that time entry.

This keeps historical cost and profitability reports accurate.

For example, if a member’s internal cost is $35/hour when a time entry is created, that entry keeps the $35/hour cost.

If the member’s internal cost is later changed to $45/hour, older time entries keep the original cost. Future time entries use the updated cost.

This prevents old reports from changing unexpectedly when member costs are updated.

Handling permission errors

If your API request fails while reading or updating member capacity or internal cost fields, check the following:

  1. The API token is valid.

  2. The request includes the correct X-Workspace-Id header.

  3. The token belongs to a user with access to that workspace.

  4. The user has an Owner or Manager role.

  5. The workspace is on a Team or Business plan.

  6. The workspace is not in a billing read-only state for write requests.

If the user does not have the correct role, use an Owner or Manager account to perform the request.

Token security

API tokens should be treated like passwords.

Do not expose tokens in client-side code, public repositories, screenshots, shared documents, or browser-based scripts.

Use environment variables or a secure secrets manager when storing tokens in applications.

If a token is no longer needed or may have been exposed, revoke it from the API token settings and create a new one.