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

Move to the new Clearstory API

Switch an existing integration from the current Web API to the new Clearstory API before the current API is turned off.

The current Clearstory Web API is being retired. It will be turned off after December 15, 2026. If your company calls https://web-api.clearstory.build with a Key ID and Key Secret, move that integration to the new Clearstory API before that date.

The new API is at https://io.clearstory.build. Credentials can be created at Settings > Advanced Settings > Web API Applications. Response shapes stay the same except in a few cases. 

Table of Contents

Why it matters

Integrations that still call the current Web API will stop working after December 15, 2026. Projects, contracts, change order requests, T&M tags, and the reference data around them will only be available from the new API after that.

Moving early gives you time to create an application, store the client secret, and check each call against the new rules while the current API is still running. New API keys for the current Web API are no longer something you can create yourself.

Where the new API lives

Call https://io.clearstory.build. Every endpoint sits under /clearstory/v1.

The reference for every endpoint, including Getting Started, Pagination, Rate Limiting, and Breaking Changes, is at https://io.clearstory.build/clearstory/docs.

Getting Credentials

The new API uses an OAuth2 client credentials application. An Account Owner creates it under Settings > Advanced Settings > Web API Applications. Clearstory shows the client secret once, at creation. The client ID stays visible in the list. You exchange the client ID and client secret for an access token, then send that token on every API call. Tokens last 24 hours by default. 

You can keep up to three applications. Deleting an application immediately cuts off access for anything still using its credentials.

Routes that moved

The following routes have changed. All others remain identical to the Legacy API, just using the new base URL and authentication. 

Current Web API

New Clearstory API

GET /companies/current

GET /company

GET /companies/current/offices

GET /offices

GET /companies/current/divisions

GET /divisions

GET /companies/current/users

GET /users

Create a Web API application

You need the Account Owner role and a Professional plan. If Web API Applications is not in the menu, email support@clearstory.build.

  1. In Clearstory, open Settings.
  2. Open Advanced Settings.
  3. Open Web API Applications.
  4. Click Create Application.
  5. Enter a Name you will recognize later, such as the system this integration talks to.
  6. Click Create.
  7. On Application Created Successfully, copy the Client ID and the Client Secret.
  8. Store the client secret in your secret manager.
  9. Click I've copied the client secret.

Clearstory will not show the client secret again. If you lose it, delete the application and create a new one.

Request an access token

Send your client ID and client secret to Clearstory's authorization server. 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). Save the token and reuse it until shortly before it expires.

Requesting a new token on every API call will get throttled. 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 new 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 GET /company response means the application can reach your company data.

Update each integration call

  1. Change the base url from https://web-api.clearstory.build to https://io.clearstory.build, and add the /clearstory/v1 prefix.
  2. Replace Basic authentication with the bearer token from the previous step.
  3. Rename any route in the table under Routes that moved.
  4. If you page with take or skip, keep them or switch to limit and offset. Keep the page size between 1 and 100. 
  5. Run your integration against the new API and compare a sample of records with what the current API returns.

Retire the current Web API connection

Leave the current integration in place until the new one has been checked. When you are done:

  1. Open Settings > Advanced Settings > Web API Keys (Legacy).
  2. Delete keys that nothing still uses.
  3. Confirm scheduled jobs, middleware, and partner systems no longer call https://web-api.clearstory.build.

You can view and delete existing keys. Creating a new key is not available in Clearstory. To request a key for the current API while you finish migrating, email support@clearstory.build.

 

Tips and best practices

  • Copy the client secret into a secret manager before you close the Application Created Successfully screen. Clearstory cannot show it again.
  • Cache the access token for its full lifetime. Refresh it shortly before the 24-hour expiry, with a little randomness, so every job does not request a token at the same moment.
  • Name the application after the system that uses it. You can have three applications. At the limit, Create Application is unavailable until you delete one.
  • Deleting an application revokes it immediately. Anything still using that client ID will start failing.
  • Page with a modest limit and walk offset forward. Prefer fromUpdatedAt and untilUpdatedAt when you only need records that changed since the last run.
  • If a scheduled job calls the API, avoid starting every run at midnight UTC or at the top of the hour.
  • Send a stable User-Agent, such as your-company-integration/1.0, on every request.
  • On 429 Too Many Requests, back off and honor Retry-After when it is present. This applies to both the token URL and the API.
  • Keep the current API running in parallel until your critical reads and writes succeed on the new API.

FAQs

  • When is the current Web API turned off? After December 15, 2026. Move before that date.

  • Will my existing Key ID and Key Secret work on the new API? No. Create a Web API application and send a bearer token. Keys from Web API Keys (Legacy) only work with https://web-api.clearstory.build.

  • Can I create a new key for the current Web API while I migrate? Email support@clearstory.build to request a key or to get help moving.

  • I don't see Web API Applications. What do I do? The menu item is there for Account Owners on a Professional plan. Confirm your role and plan. If you are the Account Owner on a Professional plan and the item is still missing, email support@clearstory.build.

  • What if I lose the client secret? Create a new application, store the new secret, point your integration at it, and delete the old application. Deleting the old one turns it off immediately.

  • Do skip and take still work? Yes. They are alternate names for offset and limit on every endpoint. The page size must be from 1 to 100. take=0 returns a 422 validation error.

  • Did response shapes change? They stay the same in the majority of cases. Authentication, and the routes in the table above are the differences to update before you switch.

  • Who is the API acting as? The application. Access is at the company level for that application's company.

  • How many applications can we have? Three. Delete one to create another. The page tells you when you are at the limit.