API reference

For a task-based example, follow the management API workflow. For application reads, use prompt retrieval.

The reference is generated from the OpenAPI specification. Each operation page describes its request and response. Examples are copyable; this documentation does not execute requests against your workspace.

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

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

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 creation is an exception: the first response includes the secret, but replay returns 409 secret_unavailable and non-secret key metadata. No duplicate key is created and no secret is retained in the receipt. If the first response was lost, explicitly revoke that key 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.

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. CLI and MCP share one request budget per person, with additional limits for expensive organization operations.

Operation groups

The generated operation pages are the canonical source for request fields and response schemas. Common entry points:

• List organizations and create a prompt.
• Read a dataset and import cases.
• Initialize a baseline, start a comparison, and read results.
• Save a version, inspect coverage, and assign a label.
• Retrieve a saved 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.