# Introduction

The LangWatch REST API: authentication, the OpenAPI document, and where each surface lives.

> Page: https://langwatch.ai/docs/api-reference/introduction
> Source: https://github.com/langwatch/langwatch/blob/main/docs/api-reference/introduction.mdx
> Index of all pages: https://langwatch.ai/docs/llms.txt

Every page in this section is generated from LangWatch's OpenAPI 3.1 document, so what you read here is what the API accepts.

## The OpenAPI document

Fetch the whole thing, unauthenticated:

```http
GET https://app.langwatch.ai/api/gateway/v1/openapi.json
```

One document covers every surface below, which is what you point a client generator, a Postman import, or an agent at. Self-hosted: same path on your own DNS.

## Authentication

Most endpoints take a project API key:

```http
X-Auth-Token: sk-lw-...
```

`Authorization: Bearer sk-lw-...` works too. Some families need an **organization** API key instead, because they carry signing secrets and organization-wide data: [webhook endpoints](https://langwatch.ai/docs/features/webhooks), [gateway spend](https://langwatch.ai/docs/ai-gateway/billing-events), and everything that provisions the organization itself, from the [organization profile](https://langwatch.ai/docs/api-reference/organization/overview) and its [members](https://langwatch.ai/docs/api-reference/members/overview) through [roles](https://langwatch.ai/docs/api-reference/roles/overview) and [grants](https://langwatch.ai/docs/api-reference/grants/overview). Create either kind under **Settings > API Keys**.

Two surfaces authenticate differently again. The [SCIM 2.0 endpoints](https://langwatch.ai/docs/api-reference/scim/overview) take a SCIM bearer token, because the caller is your identity provider. [Creating organizations on a self-hosted instance](https://langwatch.ai/docs/api-reference/organizations/overview) takes the instance administrator credential, because it runs before any organization exists.

The AI Gateway's own inference endpoints (`/v1/chat/completions` and friends) authenticate with a [virtual key](https://langwatch.ai/docs/ai-gateway/virtual-keys) rather than an API key, and live on the gateway host.

## Conventions

- Request and response fields are `lower_snake_case`.
- Money is an integer number of nano-USD (billionths of a dollar), with a decimal string rendered from it for display. The integer is the source of truth: sum integers, round once.
- Timestamps are ISO 8601, except spend and event filters, which take epoch milliseconds.
- List endpoints are cursor-paged: follow `next_cursor` until it comes back `null`. A full page does not mean there is more, and a short page does not mean there is not.
- Errors carry a stable `error.code` to branch on. See [Errors](https://langwatch.ai/docs/ai-gateway/api/errors).

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.
