> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threadi.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> A secure authentication wrapper for HubSpot's App Objects API, allowing programmatic access to StopWatch Time Logs.

<Note>
  * The **StopWatch API** can only be used by our **💫 Unlimited** subscribers. Review all subscription options [here](/pricing?app=stopwatch).
  * The **StopWatch API** is only relevant to customers using **App Objects Mode**. For customers using the legacy **Custom Objects Mode**, please use [HubSpot's Custom Objects API](https://developers.hubspot.com/docs/api-reference/latest/crm/objects/custom-objects/get-custom-object) directly.
</Note>

The **StopWatch API** acts as a secure proxy for specific HubSpot CRM Objects and Properties APIs, relevant to the [StopWatch for HubSpot](/apps/stopwatch) app. It is specifically designed to allow programmatic **read-only** access to **StopWatch Time Log** records, bypassing the scope restrictions imposed by HubSpot on App Objects.

<CardGroup cols={2}>
  <Card title="Secure Auth" icon="shield-check" iconType="duotone">
    Industry-standard Bearer token authentication with hashed storage.
  </Card>

  <Card title="Smart Pagination" icon="swap" iconType="duotone">
    Automatic rewriting of HubSpot pagination links for intuitive paging.
  </Card>

  <Card title="Header Forwarding" icon="forward" iconType="duotone">
    Critical HubSpot metadata (like rate limits) is passed directly to your app.
  </Card>

  <Card title="Fully Versioned" icon="code-branch" iconType="duotone">
    Built for long-term stability with versioned endpoints.
  </Card>
</CardGroup>

## Why use the StopWatch API?

HubSpot restricts the programmatic access to [App Object](https://developers.hubspot.com/docs/apps/developer-platform/add-features/app-objects/overview) records to the developer providing the given app. This means that while our customers can see their **StopWatch Time Log** records in HubSpot's UI, they cannot extract them programmatically using standard HubSpot API authentication methods.

The **StopWatch API** provides a secure layer that uses the StopWatch App's permissions to fetch records on your behalf, giving you the  access you need to programmatically read your **StopWatch Time Log** records.

***

## Base URL

The API's base URL is:

```http theme={null}
https://api.threadi.au
```

***

## Authentication

All requests to the **StopWatch API** must include an `Authorization` header with a static bearer <Tooltip tip="Also referred to in these docs as an API key">authentication token</Tooltip>.

```http theme={null}
Authorization: Bearer {token}
```

<Note>
  API keys can be managed from within HubSpot, within the app's **Admin Settings** tab. Only the account's **Primary Admin** can manage API keys. See our Usage Guide's [**App Settings**](/apps/stopwatch#app-settings) section for more information.
</Note>

<Warning>
  By default, each API key is **rate-limited to 1,000 requests per day** (UTC). If you need a higher daily limit, please submit a [support request](https://www.threadi.au/support?app_name=stopwatch).
</Warning>

<Frame>
  <img src="https://mintcdn.com/threadintegrations/tjD-EiuKeGVxuIBt/images/stopwatch/api-authentication-1.png?fit=max&auto=format&n=tjD-EiuKeGVxuIBt&q=85&s=5f07ff85c986b2b56a06f9723c5ec948" width="100%" data-path="images/stopwatch/api-authentication-1.png" />
</Frame>

***

## Key Features

### Link Rewriting

When you fetch a list of **StopWatch Time Log** records, HubSpot <Tooltip tip="Depending on your request configuration and how many records are available to return">might return a `paging` object</Tooltip>. We automatically rewrite these links so you can use them directly in your next request:

```json theme={null}
"paging": {
  "next": {
    "after": "12345",
    "link": "https://api.threadi.au/stopwatch/v1/timelogs?limit=10&after=12345"
  }
}
```

### Response Headers

The following `x-stopwatch-*` headers are supplied in the majority of cases:

| key                                                                                                                                                                                     | example         |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| <Tooltip tip="The maximum number of requests allowed in the current rate-limit window."><code>x-stopwatch-ratelimit-max</code><Badge icon="circle-info" color="blue" /></Tooltip>       | `1000`          |
| <Tooltip tip="The number of requests still available in the current rate-limit window."><code>x-stopwatch-ratelimit-remaining</code><Badge icon="circle-info" color="blue" /></Tooltip> | `123`           |
| <Tooltip tip="Unix timestamp (milliseconds) for when the rate-limit window resets."><code>x-stopwatch-ratelimit-reset</code><Badge icon="circle-info" color="blue" /></Tooltip>         | `1774913275000` |

We also forward all `x-hubspot-*` headers from the underlying HubSpot response. This allows your integration to monitor rate limits in real-time. These headers could include:

* `x-hubspot-correlation-id`
* `x-hubspot-ratelimit-interval-milliseconds`
* `x-hubspot-ratelimit-max`
* `x-hubspot-ratelimit-remaining`
* `x-hubspot-ratelimit-secondly`
* `x-hubspot-ratelimit-secondly-remaining`

Learn more about how to interpret these HubSpot headers [here](https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines#rate-limit-error-responses).

***

Next, explore our [API Reference](/apis/stopwatch/list-time-logs) to start building.