save version

Save an immutable version from the current user’s exact draft revision. Requires completed setup and an active prompt. No evaluation requirement and no automatic label changes. Idempotent replay returns the original version.

POST/api/v1/organizations/{organizationId}/prompts/{promptId}/versions

Authorization

ManagementOAuth management

AuthorizationBearer <token>

User-based Clerk OAuth. CLI is a public Authorization Code client using S256 PKCE and browser loopback redirect. Hosted MCP uses resource-bound OAuth. Verify issuer, token type, intended audience/resource, scopes, live membership and current role. Do not forward arbitrary OAuth tokens into Convex session JWT auth. OAuth URLs below are placeholders for deployment configuration.

In: header

Scope: management

Path Parameters

organizationId*string

Permanent organizationId; selected organization must be authorized for the current user.

promptId*string

Permanent promptId; selected organization must be authorized for the current user.

Header Parameters

Idempotency-Key*string

Management writes: scoped to OAuth user+client+organization+operation. Store request digest and response for at least 24 hours. Same key/body replays original response, including after completion; different body fails idempotency_conflict. Exception: create_retrieval_key stores a non-secret receipt referencing the created key, never its secret. Same-key/body retries return 409 secret_unavailable with existing key metadata and do not create another key. Evaluation creation must not execute twice.

Length8 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/organizations/string/prompts/string/versions" \  -H "Idempotency-Key: stringst" \  -H "Content-Type: application/json" \  -d '{    "draftRevision": 0  }'

{  "id": "string",  "number": 1,  "content": {    "messages": [      {        "role": "system",        "content": "string"      }    ],    "inputType": "user_message",    "modelId": "string",    "modelRouteId": "string",    "temperature": 0,    "outputSchema": "string",    "customMetrics": [      {}    ]  },  "createdAt": "2019-08-24T14:15:22Z",  "createdBy": "string"}

POST/api/v1/organizations/{organizationId}/prompts/{promptId}/versions

Authorization

ManagementOAuth management

AuthorizationBearer <token>

In: header

Scope: management

Path Parameters

organizationId*string

Permanent organizationId; selected organization must be authorized for the current user.

promptId*string

Permanent promptId; selected organization must be authorized for the current user.

Header Parameters

Idempotency-Key*string

Length8 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

draftRevision*integer

Range0 <= value

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/organizations/string/prompts/string/versions" \  -H "Idempotency-Key: stringst" \  -H "Content-Type: application/json" \  -d '{    "draftRevision": 0  }'

{  "id": "string",  "number": 1,  "content": {    "messages": [      {        "role": "system",        "content": "string"      }    ],    "inputType": "user_message",    "modelId": "string",    "modelRouteId": "string",    "temperature": 0,    "outputSchema": "string",    "customMetrics": [      {}    ]  },  "createdAt": "2019-08-24T14:15:22Z",  "createdBy": "string"}

Account and organizations

Members and invitations

Prompts and drafts

Versions and labels

Datasets

Evaluations

Model access

Retrieval keys

Billing

Warnings and observability

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

503application/json

Account and organizations

Members and invitations

Prompts and drafts

Versions and labels

Datasets

Evaluations

Model access

Retrieval keys

Billing

Warnings and observability

save version

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`