# API reference | PromptLens Docs OpenAPI requests, responses, authentication, concurrency, and retry behavior. For a task-based example, follow the [management API workflow](https://www.promptlens.io/docs/integrations/management-api). For application reads, use [prompt retrieval](https://www.promptlens.io/docs/integrations/retrieval). The reference is generated from [the OpenAPI specification](https://www.promptlens.io/openapi.json). Each operation page describes its request and response. Examples are copyable; this documentation does not execute requests against your workspace. ## Authentication [#authentication] Management requests use a Clerk OAuth access token with the `management` scope and the canonical `https://www.promptlens.io/api/v1` resource. MCP tokens target `/mcp` and cannot be reused for API calls. Browser session tokens and `plr_` retrieval keys do not authorize management requests. For a custom OAuth client, start with the protected-resource metadata advertised by the API's 401 challenge. Use its advertised authorization server and OAuth metadata to configure an authorization-code flow with PKCE, the management resource, and the required scope. Register your client's redirect URL and client ID as required by that server, then complete browser sign-in and consent. Keep access and refresh credentials in private storage; do not reuse a token issued for another resource. Send the access token in the `Authorization: Bearer …` header. A 401 response advertises OAuth protected-resource metadata. Tokens are checked online on each request, including retries. ## Selecting an organization [#selecting-an-organization] Organization-scoped paths include `organizationId`. The server verifies current membership and role; knowing an ID does not grant access. Account-level profile and membership listing work before an organization has been selected. ## Idempotency and revisions [#idempotency-and-revisions] Send `Idempotency-Key` for operations that require it. Reuse the same key and identical request when recovering an unknown outcome. Receipts are retained for at least 24 hours. Changing the request while reusing its key returns an idempotency conflict. Retrieval-key and webhook-endpoint creation are exceptions: the first response includes the secret, but replay returns `409 secret_unavailable` with non-secret metadata in `error.details.key` or `error.details.endpoint`. No duplicate is created and no secret is retained in the receipt. If the first response was lost, explicitly revoke that key or endpoint and create a replacement with a new idempotency key. Revision checks prevent lost updates. Read the latest revision before editing; do not automatically replace a stale revision and retry a write. ## Long-running evaluations [#long-running-evaluations] Evaluation requests are asynchronous. [Initialize](https://www.promptlens.io/docs/api-reference/operations/initialize_baseline), [start](https://www.promptlens.io/docs/api-reference/operations/start_evaluation), [retry](https://www.promptlens.io/docs/api-reference/operations/retry_evaluation_side), and [resume](https://www.promptlens.io/docs/api-reference/operations/resume_evaluation) return `202` once the run is queued, with its run ID and a `statusUrl` path relative to the API origin. A comparison returns `candidateStatusUrl` and `productionStatusUrl`. No request stays open while models run. To be notified instead of polling, register an [evaluation webhook](https://www.promptlens.io/docs/integrations/webhooks). Otherwise [read the run](https://www.promptlens.io/docs/api-reference/operations/get_evaluation) at its status URL, waiting the number of seconds in `Retry-After` between reads. Send the previous response's `ETag` as `If-None-Match` to receive an empty `304` when nothing changed. The response reports `status`, `completedCases` of `totalCases`, aggregate counts, and `error`. `pending` means queued and `running` means executing; `completed`, `failed`, and `cancelled` are final. Stop polling on `paused`: inspect its error, resolve the plan or usage limit, then resume explicitly. After completion, page through `resultsUrl`. A replay of a request accepted before status URLs were added may omit them; use `/api/v1/organizations/{organizationId}/evals/{evaluationId}` with the returned run ID. [Listing evaluations](https://www.promptlens.io/docs/api-reference/operations/list_evaluations) shows each run's stored status; read the run itself for its current status. If a submission response is lost, retry the identical request with the same `Idempotency-Key`. The replay returns the original run IDs without queueing or charging again. A dropped status read is safe to repeat. ## Pagination and errors [#pagination-and-errors] Lists return `items` and `nextCursor`. Use the returned cursor for the next page. Errors contain `error.code` and `error.message`, with `error.requestId` when available. Respect `Retry-After` on rate-limit responses. Management clients share one request budget per person, with additional limits for expensive organization operations. ## Operation groups [#operation-groups] The generated operation pages are the canonical source for request fields and response schemas. Common entry points: * [List organizations](https://www.promptlens.io/docs/api-reference/operations/list_organizations) and [create a prompt](https://www.promptlens.io/docs/api-reference/operations/create_prompt). * [Read a dataset](https://www.promptlens.io/docs/api-reference/operations/get_dataset) and [import cases](https://www.promptlens.io/docs/api-reference/operations/import_dataset). * [Initialize a baseline](https://www.promptlens.io/docs/api-reference/operations/initialize_baseline), [start a comparison](https://www.promptlens.io/docs/api-reference/operations/start_evaluation), and [read results](https://www.promptlens.io/docs/api-reference/operations/list_evaluation_results). * [Save a version](https://www.promptlens.io/docs/api-reference/operations/save_version), [inspect coverage](https://www.promptlens.io/docs/api-reference/operations/get_version_coverage), and [assign a label](https://www.promptlens.io/docs/api-reference/operations/assign_label). * [Register an evaluation webhook](https://www.promptlens.io/docs/api-reference/operations/create_webhook_endpoint) to be notified when runs finish. * [Retrieve a saved prompt](https://www.promptlens.io/docs/api-reference/operations/retrieve_prompt) with a prompt-scoped retrieval key. Both retrieval and management requests use `https://www.promptlens.io`. Retrieve saved prompts at `/api/v1/prompts/{promptId}` with a prompt-scoped retrieval key; management operations use their organization or account paths and OAuth credentials. ## Bulk operations [#bulk-operations] [Dataset import](https://www.promptlens.io/docs/api-reference/operations/import_dataset) accepts an array of rows in a single request, with append or replace mode and a current dataset revision. Review replacement before submitting: it changes shared cases. Trace ingestion also accepts event batches under its [separate ingestion contract](https://www.promptlens.io/docs/reference/trace-ingestion). There is no general-purpose array of arbitrary management operations; use each operation's idempotency and concurrency requirements. ## Versioning and deprecation [#versioning-and-deprecation] REST URLs use `/api/v1`. Backward-compatible additions may introduce optional fields or operations; clients should tolerate unknown response fields. Breaking changes use a new major URL version rather than silently changing the current contract. No retirement of v1 is currently scheduled. When a version is deprecated, PromptLens will publish migration guidance and a retirement date in this reference, with at least 90 days' notice except where an urgent security or legal change requires a shorter window. Deprecated endpoints will advertise `Deprecation`, `Sunset`, and a `Link` with `rel="deprecation"`; clients should retain those headers and follow the linked migration guidance. These headers are not sent for active, nondeprecated endpoints.