Setup

The OutEvalAI API lets an existing CRM, operations system, or internal application manage the same core records your team uses in the dashboard. Use it to provision agents, synchronize leads, configure calling use cases, run agent evaluations, and read test outcomes without duplicating manual work.

Open the generated API Reference to browse every supported endpoint, request and response schema, code example, and the interactive playground.

API prefixes

API Key

Create and manage API keys from the workspace topbar or admin options.

• Click View API Key in the dashboard header
• Copy your workspace API key

Treat an API key like a password. Keep it in a server-side secret manager, send it only over HTTPS, and never place it in browser code, screenshots, support messages, source control, or a Postman shared initial value. Create separate keys for separate environments or integrations so each one can be revoked independently.

Headers

Authorization: Bearer <api-key>

Base URL

Production:

https://outevalai.com

Example:

curl https://outevalai.com/api/v1/public/workspace \
  -H "Authorization: Bearer <api-key>"

Errors and request IDs

Every public API response includes an X-Request-ID header. Send your own safe request ID when you need to correlate a request across systems, or let OutEvalAI generate one. Include this value when contacting support.

Errors use one stable envelope:

{
	"error": {
		"code": "validation_error",
		"message": "Unprocessable Entity",
		"request_id": "a72d84c2-7e36-4a3e-a9cc-e6adad589e17",
		"retryable": false,
		"details": []
	}
}

The HTTP status remains authoritative. The retryable field identifies transient failures that may succeed when repeated without changing the request. For mutations, it is true only when the request included an Idempotency-Key backed by persisted replay semantics. Clients must additionally confirm that the operation supports idempotency before retrying. The details field is optional and may contain structured validation context.

Pagination

Agent, usecase, lead, and call list endpoints support opt-in cursor pagination:

• send limit from 1 to 100;
• read X-Next-Cursor and X-Has-More from the response;
• send the returned cursor unchanged as the next request's cursor;
• stop when X-Has-More is false.

Existing integrations that omit both limit and cursor retain the original unpaginated v1 response. New integrations should always request bounded pages. A request containing cursor but no limit uses a page size of 50.

Rate limits and retries

Rate-limited responses use status 429 and include Retry-After plus X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers when available. Retry 429, transient 5xx, and network timeouts with bounded exponential backoff and jitter. Honor Retry-After when present.

Do not automatically retry create, update, or delete requests after an ambiguous timeout unless the operation documents Idempotency-Key support and the caller supplied a stable key. Agent creation and lead creation currently support persisted replay semantics; other mutations do not.

API reference

Authenticated REST API

Integration pattern

For a reliable integration, store OutEvalAI IDs alongside your corresponding internal records.

1. Create or select an agent, then store its agent_id in your integration configuration.
2. Create personas and scenarios to evaluate your agent automatically.
3. Start evaluation runs and inspect pass/fail results, transcripts, and AI suggestions.
4. Make retries idempotent in your own worker: record successful IDs before retrying a batch.
5. Treat 401 as an invalid or revoked key, 403 as a workspace entitlement or policy restriction, 404 as an ID outside the authenticated workspace, and 422 as invalid request data.

The interactive playground sends requests through the OutEvalAI docs server so the key is never embedded in client-side source. The key remains in memory only while the playground is open and is cleared when it closes, navigates, or unloads. For production integrations, make requests from your own backend rather than from a public browser session.