> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Call the public Ona Connect API from scripts, services, and generated clients.

The Ona API is a [Connect](https://connectrpc.com/) RPC API for managing Ona resources. Service and method pages are generated directly from the public Protocol Buffer definitions whenever the API is generated.

## Use the API base URL

Send requests to `https://app.ona.com/api`.

<Note>
  If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain. Create and use tokens from the same domain.
</Note>

## Authenticate requests

Send a [personal access token](/docs/ona/integrations/personal-access-token) or [service account token](/docs/ona/organizations/service-accounts) as a Bearer token in the `Authorization` header.

```bash theme={null}
export ONA_HOST=https://app.ona.com
export ONA_API_KEY=<your-token>

curl --request POST \
  --url "$ONA_HOST/api/gitpod.v1.EnvironmentService/ListEnvironments" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{}'
```

Tokens inherit the permissions of their user or service account. A request fails when the token does not grant the permission required by the method.

## Send Connect requests

Unary methods accept `POST` requests with Protocol Buffer JSON request bodies. The generated method pages list the route, RPC cardinality, request fields, response fields, validation constraints, and a copyable example.

Protocol Buffer JSON differs from ordinary JSON in a few places:

* Field names use their lower camel-case JSON name, such as `environmentId`.
* Enum values use symbolic names, such as `ENVIRONMENT_PHASE_RUNNING`.
* 64-bit integers are strings.
* `bytes` fields are base64-encoded strings.
* Timestamps use RFC 3339 strings and durations use strings such as `60s`.
* Unknown fields are rejected.

Server-streaming methods use Connect message envelopes with `application/connect+json` or `application/connect+proto`. Use a generated Connect client for streaming rather than sending an unframed JSON body directly.

## Handle errors

Connect errors contain a machine-readable code and message. Treat authentication and permission errors separately from validation failures, and do not retry requests with invalid arguments. Retry transient errors such as `unavailable` with exponential backoff.

Never log Bearer tokens or secret request fields when recording failed requests.