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

# API overview

Choose a resource in the sidebar to see its endpoints. Each page shows the request, the response, and the errors that endpoint can return.

To set up your first agent and test suite, start with the [Skills and CLI guide](/skills-cli-sdks/skills-and-cli).

## Authentication

Send an Egma API key in the `Authorization` header:

```http theme={"system"}
Authorization: Bearer <your-egma-api-key>
```

You can create a project key from a repository that is already connected to Egma:

```bash theme={"system"}
egma project api-key create --name "My API integration"
```

Copy the key when the command prints it. Egma shows the secret once. Store it in your environment or secret manager.

Browser requests can use the signed-in Egma session cookie. Use API keys for your scripts, CI jobs, and services.

Project keys cannot read organization-wide members, provider-key metadata, usage, or billing, or manage organizations, members, or projects. They can create, list, and revoke keys only within their own project and the creator's current role. When creating a key with a project key, explicitly supply that same `projectId`. Use a browser session or organization key for organization-wide operations.

## Make a request

Examples use hosted Egma at `https://app.egma.ai`. If you self-host Egma, use your instance's public URL.

Set `EGMA_API_KEY` to your key, then list your test suites:

```bash theme={"system"}
export EGMA_URL="https://app.egma.ai"

curl --fail-with-body "$EGMA_URL/v1/test-suites" \
  --header "Authorization: Bearer $EGMA_API_KEY"
```

The response contains a `testSuites` array. Use a suite's `id` when you [create a run](/api-reference/create-a-run).

For a request with a JSON body, also send `Content-Type: application/json`.

## Projects

A project key acts only in the project it was created for. You can leave `projectId` out when you use that key.

An organization key can access its organization's projects. For an endpoint that needs one project, send `projectId` if the organization has more than one. The endpoint page shows whether it belongs in the query or body.

Use [List projects](/api-reference/list-projects) to find project IDs. Sending a different `projectId` does not expand a key's access.

## Pagination

Endpoints that return pages accept `pageSize` and `pageToken`. Read `nextPageToken` from the response and pass it as `pageToken` on the next request. Keep the other filters the same. Stop when `nextPageToken` is `null`.

Each endpoint page lists its page size limits and required filters. For example, [List tests](/api-reference/list-tests) requires `suiteId`.

[Run events](/api-reference/list-run-events) use a different cursor. Pass the returned `next` value as `after`. A response with `caughtUp: true` means you have read the events available so far. Keep polling until `done: true`; execution and grading may still be in progress.

## Errors and retries

Egma returns errors as JSON. Read `error` for the error code and `message` for what to do next. Some errors also include `details`.

| Status | What to do                                                                      |
| ------ | ------------------------------------------------------------------------------- |
| `400`  | Check the request fields and query parameters.                                  |
| `401`  | Check your API key or sign in again.                                            |
| `403`  | Use a credential with access to the requested action and project.               |
| `404`  | Check the resource ID and project.                                              |
| `409`  | Read the error code. A name, version, or resource state may conflict.           |
| `422`  | Fix the values or resource state described in the response.                     |
| `429`  | Wait for the number of seconds in `Retry-After`, then retry.                    |
| `503`  | Read the message. A provider or a service the request needs may be unavailable. |

For temporary network or service failures, wait before you retry. Increase the delay between attempts and set a retry limit.

Each accepted run creation request creates a new run, even when its input matches an earlier request. After a lost response, check the run list before submitting again. Other writes also need a state check before retrying an uncertain request.

## Send traces

For LiveKit, use the [Python SDK](/skills-cli-sdks/sdks/livekit-python) or [JavaScript SDK](/skills-cli-sdks/sdks/livekit-javascript). Call `simulation(agent, ctx, session)` for simulation evidence and `monitor(ctx)` for production monitoring. Both use Egma’s OTLP endpoint, `POST /v1/traces`, with a project-scoped API key. Retell monitoring reads conversations through the Retell API.

## OpenAPI

These endpoint pages are generated from the same contract as the platform API and its internal client. Request fields, response fields, and status codes come from that contract.

[Download the OpenAPI specification](/openapi.json). The file uses a relative server URL so you can use it with hosted or self-hosted Egma.