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

# Getting started with the Operata API

> Authenticate with HTTP Basic, make your first call, and read the paginated response envelope Operata returns from every list endpoint.

The Operata API gives you programmatic access to every contact, observation, and insight your collectors have stored. You authenticate with HTTP Basic — your Group ID as username, your API token as password — then hit `https://api.operata.io`. This guide walks you through generating credentials, making your first call, and reading the paginated response envelope.

## Before you start

* An [Operata account](https://app.operata.io). Your **Operata Group ID** is the UUID in the console URL.
* The Admin role on that account. The console exposes token creation under **Settings → Config → API**.
* `curl` (any recent version) and a shell that exports environment variables.

## Steps

### 1. Generate an API token

In the Operata console, go to **Settings → Config → API** and click **Create token**. Copy the token immediately — the console shows it once. Treat tokens like passwords.

```bash theme={null}
export OPERATA_GROUP_ID="a28453f9-abab-cdcd-efef-84d9e67ac297"
export OPERATA_API_TOKEN="paste-your-token-here"
```

You now have credentials in your shell. See [Authentication](/docs/api-authentication) for the full credential lifecycle.

### 2. Make your first call

Operata uses HTTP Basic. The Group ID is the username, the token is the password. Hit the contact summary endpoint with a small window:

```bash theme={null}
curl -u "$OPERATA_GROUP_ID:$OPERATA_API_TOKEN" \
  "https://api.operata.io/v1/data/calls?fromTime=2026-05-17T00:00:00Z&toTime=2026-05-18T00:00:00Z&size=1"
```

A `200 OK` confirms your credentials are valid and the account has access to contact data.

### 3. Read the response envelope

Every list endpoint returns the same envelope: a `data` array and a `next_cursor` you follow for the next page.

```json theme={null}
{
  "data": [
    {
      "id": "ctr_0HXYZ123456789ABCDE",
      "started_at": "2026-05-17T15:02:11Z",
      "duration_ms": 184200
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjUwfQ=="
}
```

You parse `data` for the records and re-send the request with `cursor=<next_cursor>` to walk further. See [Pagination](/docs/api-pagination) for the loop pattern.

### 4. Handle errors and rate limits

Operata returns a stable JSON error envelope on every 4xx and 5xx:

```json theme={null}
{ "error": { "status": 401, "code": "unauthorized", "message": "Invalid credentials." } }
```

Match on `error.code`, not on `error.message`. Honor the `Retry-After` header on `429 rate_limited` — the default budget is 100 requests per minute per token. See [Errors](/docs/api-errors) and [Rate limits](/docs/api-rate-limits).

## Verify

Run the call from step 2 again and confirm three things:

* The HTTP status is `200`.
* The body parses as JSON with a `data` array.
* The response headers include `X-RateLimit-Remaining` with a value below 100.

If you see `401 unauthorized`, your Group ID and token do not pair correctly — re-check the env vars. If you see `400 invalid_range`, the time window is malformed; the `toTime` must be strictly after `fromTime`.

## Related

* [Quickstart](/docs/quickstart) — the 90-second version of this guide, when you want the curl line and nothing else.
* [Pagination](/docs/api-pagination) — walk every page of a result set with one cursor variable.
* [Contact summary](/docs/api-contact-summary) — the first endpoint most integrations call.
* [Data redaction](/docs/api-data-redaction) — strip sensitive fields before they reach Operata.