> ## 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 (v1)

> Authenticate with HTTP Basic, make your first call, and read the JSON array 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 response in the v1 format. For the v2 data model, see [Getting started](https://docs.operata.com/docs/api-getting-started.md).

## 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](https://docs.operata.com/docs/api-authentication.md) 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

List endpoints return a plain JSON array. The `RecordCount` response header holds how many records match in total.

```json theme={null}
[
  {
    "softphoneSummary": {
      "contactId": "56f36f8c-463e-44fe-aff7-54ea7533cec1",
      "agentUserName": "agent_42",
      "networkType": "wlan"
    },
    "contactDurationSummary": {
      "contactDurationRoundedMin": 1,
      "contactDurationActualSec": 19
    }
  }
]
```

To get the next page, re-send the request with `from` set to the number of records you've already read. See [Pagination](https://docs.operata.com/docs/api-pagination.md) for the loop pattern.

### 4. Handle errors

Errors come back as an HTTP status code with a short plain-text body. A bad query parameter returns `400` with a message naming it:

```text theme={null}
query parameter "toTime" must be after "fromTime"
```

Branch on the status code and log the body. See [Errors](https://docs.operata.com/docs/api-errors.md) for every status, and [Rate limits](https://docs.operata.com/docs/api-rate-limits.md) for request budgets.

## Verify

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

* The HTTP status is `200`.
* The body parses as a JSON array.
* The `RecordCount` response header is present.

If you see `401`, your Group ID and token don't pair correctly. Re-check the env vars. If you see `400`, read the body: it names the query parameter to fix.

## Related

* [Quickstart (v1)](https://docs.operata.com/docs/quickstart-v1.md) — the 90-second version of this guide, when you want the curl line and nothing else.
* [Pagination](https://docs.operata.com/docs/api-pagination.md) — walk every page of a result set with `from` and `size`.
* [List contact summaries](https://docs.operata.com/docs/api-contact-summary.md) — the first endpoint most integrations call.
* [Data redaction](https://docs.operata.com/docs/api-data-redaction.md) — strip sensitive fields before they reach Operata.


## Related topics

- [How Operata works](https://docs.operata.com/docs/get-started-architecture.md)
- [Overview](https://docs.operata.com/docs/get-started-overview.md)
- [API changelog](https://docs.operata.com/docs/api-changelog.md)