Skip to main content
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.

​
Authentication

Send an Egma API key in the Authorization header:
You can create a project key from a repository that is already connected to Egma:
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:
The response contains a testSuites array. Use a suite’s id when you 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 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 requires suiteId. 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. 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 or JavaScript SDK. 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. The file uses a relative server URL so you can use it with hosted or self-hosted Egma.