# Use the public API reference

Find an endpoint contract, identify its scope, and build an authenticated request.

## Before you start

### Intended audience

Developers and operators who integrate with the Tellagen HTTP API.

### Required permissions

Anyone can read the API Reference. API requests need a key with the endpoint's Scope.


### Prerequisites

- Know the operation that the integration must perform.

## Procedure

<a id="phase-find-the-contract"></a>

### Find the contract

<a id="step-open-the-reference"></a>

1. **Open the reference.** Open the [API reference](https://tellagen.com/api-reference). You do not need an API key to read it.

<a id="step-search-endpoints"></a>

2. **Search endpoints.** Use Find an endpoint. Search by path or purpose.

<a id="step-filter-the-results"></a>

3. **Filter the results.** Use Method and Scope to narrow the endpoint list.

<a id="step-read-the-contract"></a>

4. **Read the contract.** Open an endpoint. Read its scope, example request, and success status. Expand the contract for field rules and Errors and recovery for failures.

![API Reference endpoint finder and an incident endpoint contract with its required scope.](https://tellagen.com/help/assets/api-reference-endpoint-contract-2026-08-29.webp)

Use the endpoint finder, then read the Scope in the selected contract.

<a id="step-use-the-markdown-index"></a>

5. **Use the Markdown index.** Open the [Markdown endpoint index](https://tellagen.com/api-reference.md). Use its links to open endpoint details.

<a id="phase-call-the-api"></a>

### Call the API

<a id="step-create-a-scoped-key"></a>

6. **Create a scoped key.** Create and store a [scoped API key](https://tellagen.com/help/manage-api-keys#step-create-and-store-the-token) with the endpoint's Scope.

<a id="step-send-a-safe-test-request"></a>

7. **Send a safe test request.** Send [GET /api/v1/incidents](https://tellagen.com/api-reference/incidents#incidents-endpoint-get-api-v1-incidents) with the header `Authorization: Bearer tllg_YOUR_TOKEN`. A successful request returns 200 OK and a JSON incident list.

Safe request with placeholders:

```shell
curl 'https://YOUR_WORKSPACE.api.tellagen.com/api/v1/incidents' \
  -H 'Authorization: Bearer tllg_YOUR_TOKEN' \
  -H 'Accept: application/json'
```

<a id="step-review-the-response"></a>

8. **Review the response.** Compare the status and response body with the documented contract. Handle documented errors explicitly.

## You are done when…

The request uses the documented path and minimum scope, and its response matches the endpoint contract.

## Troubleshooting

<a id="troubleshooting-the-api-returns-a-scope-error"></a>

### The API returns a scope error.

Create a replacement key with the exact scope shown for that endpoint. Store it before revoking the old key.

<a id="troubleshooting-the-markdown-reference-differs-from-the-html-page"></a>

### The Markdown reference differs from the HTML page.

Treat the generated reference as one canonical source and report a contract mismatch before building against it.

<a id="troubleshooting-the-api-returns-an-authentication-error"></a>

### The API returns an authentication error.

Make sure that the token is active. Retry the read-only request with Bearer tllg_YOUR_TOKEN. The request does not change incident data. If authentication still fails, ask a workspace manager to review the key.

<a id="troubleshooting-the-endpoint-is-hard-to-find"></a>

### The endpoint is hard to find.

Clear the filters. Search by a stable path term such as incidents, timeline, or postmortems.

## Related articles

- **Recommended next task:** [Manage workspace API keys](https://tellagen.com/help/manage-api-keys)
- [Run a local Diagnosis for an incident](https://tellagen.com/help/run-local-diagnosis)
- [API Reference](https://tellagen.com/api-reference)


## Continue through the incident lifecycle

- **Previous task:** [Check workspace incident readiness](https://tellagen.com/help/check-incident-readiness)
- **Next task:** [Declare an incident in the web app](https://tellagen.com/help/declare-an-incident)
- [Back to Support Center](https://tellagen.com/help#help-search)

## Last verified date

2026-08-29