Skip to content
Go to Home Page
  • There are no suggestions because the search field is empty.

Using the Clearstory API

Create an application and call the Clearstory API to access your company's data. 

The Clearstory API lets your systems read and manage projects, contracts, change order requests, T&M tags, and the reference data that ties them together.

An Account Owner on a Professional plan creates an application in Clearstory. Your integration then exchanges that application's client ID and client secret for an access token and sends the token on each request.

If you have an integration using the Legacy API (base url:https://web-api.clearstory.build ), use Move to the new Clearstory API instead of this article.

Access requirements

  • Only Account Owners can open Web API Applications.
  • Applications are available only on Professional plans.
  • If you do not see Web API Applications, email support@clearstory.build.

Endpoint details, filters, and examples are in the API reference at https://io.clearstory.build/clearstory/docs.

Start with Getting Started on that page, then use the API Reference for each resource.

Create an application

  1. In the left navigation menu, click Settings.
  2. Under Advanced Settings, select Web API Applications.
  3. Click Create Application.
  4. Enter a Name you will recognize later, such as the system this integration talks to.
  5. Click Create.
  6. On Application Created Successfully, copy the Client ID and the Client Secret.
  7. Store the client secret in a password manager or in encrypted environment variables.
  8. Click I've copied the client secret.

Clearstory shows the client secret once. You will not be able to see it again after you close the window. The client ID stays in the applications list. If you lose the secret, delete the application and create a new one.

You can have three applications. At the limit, the page says Limit of 3 applications reached. Delete one to create another.

Request an access token

Send the client ID and client secret to Clearstory. The audience value must be exactly https://io.clearstory.build.

curl -s https://auth.clearstory.build/oauth/token \   -H 'Content-Type: application/json' \   -d '{     "grant_type": "client_credentials",     "client_id": "YOUR_CLIENT_ID",     "client_secret": "YOUR_CLIENT_SECRET",     "audience": "https://io.clearstory.build"   }'

The response includes an access_token and an expires_in lifetime (24 hours by default). Save the token and reuse it until shortly before it expires. Request a new one a little early, and not at the same moment for every job. If the token request returns 429 Too Many Requests, wait and try again. When the response includes a Retry-After header, wait at least that long.

Call the API

Send the access token on every request, plus a User-Agent that names your integration. A blank or missing User-Agent returns 400. A missing, expired, or malformed token returns 401.

curl https://io.clearstory.build/clearstory/v1/company \   -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \   -H 'User-Agent: my-integration/1.0'

A successful response from GET /company means the application can reach your company data. The application acts for the company, not as an individual Clearstory user.

When you only need records that changed since the last run, use fromUpdatedAt and untilUpdatedAt on list endpoints that support them.

Delete an application

  1. On Web API Applications, click the trash icon next to the application.
  2. Click Delete when prompted.

Deleting an application revokes it immediately. Any integration still using that client ID loses access. This cannot be undone.

Security best practices

  • Treat the client secret like a password. Do not share it.
  • Copy it before you close Application Created Successfully.
  • Use a separate application for each environment, such as development and production. You can have three.
  • Cache the access token for its 24-hour lifetime. Do not request a new token on every API call.
  • Send a stable User-Agent, such as your-company-integration/1.0, on every request.
  • On 429 Too Many Requests, wait and try again. Honor Retry-After when it is present. This applies to both the token URL and the API.
  • If a job runs on a schedule, avoid starting every run at midnight UTC or at the top of the hour.

Need help?

Email support@clearstory.build if you do not see Web API Applications, you need help creating an application, or a request returns an error you cannot resolve.