# FAQ

Quick answers to the questions developers ask most about the Buildertrend API.

## Access

**How do I get access?**
The API is in early access. [Join the waitlist](https://developer.buildertrend.com/waitlist) and we'll email you when your spot opens. Signing in to the developer portal needs early access on your Buildertrend account.

**Is there a sandbox?**
Not yet. Every call reads and writes a real Buildertrend account. Try new code on a job you can throw away before you point it at a live job.

## Tokens and linking

**How long does an access token last?**
A client credentials token lasts 30 minutes. There's no refresh token, so request a new one when it expires. A user sign-in token lasts 24 hours and comes with a refresh token.

**How long does a refresh token last?**
A user sign-in refresh token lasts 30 days, or 15 days without use, whichever comes first. Every refresh returns a new refresh token and retires the old one, so always store the new one.

**My calls return `401 api_key_not_linked`. Why?**
The token is fine, but the app isn't linked to a Buildertrend account yet. On your app's page in [My apps](https://developer.buildertrend.com/apps), choose Link Buildertrend account and sign in as the user the integration should act as.

**My calls suddenly return `401 reauthorization_required` or `401 api_key_not_linked`. Why?**
The app's link to its Buildertrend account expired or was revoked. A link lasts 30 days. Right after it expires you get `reauthorization_required`. Once the expired link is cleared, usually within a day, you get `api_key_not_linked`. Link the app again from its page in My apps. A `502 token_exchange_failed` is different: Buildertrend sign-in couldn't be reached, so retry with backoff.

**Whose permissions does my app have?**
Exactly the linked user's. An app sees and changes only what that person can in Buildertrend. Every write lands on the job under their name. Link it to a user who can see only what the integration needs. [Permissions](https://developer.buildertrend.com/docs/permissions) has the details.

## Limits and behavior

**What's the rate limit?**
60 requests a minute per app, counted across every endpoint. With user sign-in, it's 60 a minute per signed-in person. Past that you get `429 rate_limited`. Wait, then retry with backoff.

**Can I delete records through the API?**
No. You can read, create and update, but nothing can be deleted through the API.

**Why do I get a `403` or `404` for a record I know exists?**
The linked user can't see it, or doesn't have the permission the call needs in Buildertrend. "Doesn't exist" and "not yours" look the same, by design.

**Can I call the API from a web page in the browser?**
Browsers block it. The API only accepts browser calls from this developer portal, for Try it. Call it from your server, a script or a backend function instead.

**How do I know when something changes?**
Read the [release notes](https://developer.buildertrend.com/release-notes). Each week lists what reached production, and calls out anything you need to update in your code.

## Building

**I can't find an endpoint or field I need. What should I do?**
Check [APIs](https://developer.buildertrend.com/apis/open-api) for everything that's live today. If it isn't there, tell us what you're trying to build through [Support](https://developer.buildertrend.com/support). Requests from builders using the API shape what we build next.

**Can I use an AI coding tool?**
Yes. [Build with AI](https://developer.buildertrend.com/use-cases) has a prompt to paste first, plus prompts for common integrations. Give your tool https://developer.buildertrend.com/llms.txt and the spec.

**How do I learn how a Buildertrend feature works?**
The [Help Center](https://buildertrend.com/help-articles/) and [Learning Academy](https://buildertrend.com/buildertrend-learning-academy/) cover every part of Buildertrend.

**Something isn't working. What should I do?**
Check [Errors](https://developer.buildertrend.com/errors) for the code you got. If that doesn't fix it, contact [Support](https://developer.buildertrend.com/support).
