Update, commit, or deploy prompts in bulk
https://api.respan.ai/api/prompts/bulk/Process 1 to 100 prompt operations sequentially in request order using exact prompt_id matching. Each item runs in its own transaction, so a failed item is rolled back without undoing successful items. update changes model configuration on the latest draft and does not accept content fields such as messages, variables, or description; commit snapshots the latest draft; deploy promotes the latest committed version. A later duplicate successful commit or deploy for the same prompt in one request is returned as an indexed error. This endpoint inherits the caller’s configured API-key or JWT rate limits; it has no fixed endpoint-specific RPM.
Servers
https://api.respan.ai: Respan API Server
Authentication
RespanApiKey
Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.
HTTP scheme: bearer; format: Respan API key.
Authorization: Bearer $RESPAN_API_KEYOr:
DashboardJwt
Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.
HTTP scheme: bearer; format: Dashboard JWT.
Authorization: Bearer $RESPAN_DASHBOARD_JWTRequest body
A request body is required.
application/json
$ object Required body
Reference:
#/components/schemas/PromptBulkRequestAdditional properties are not allowed
requests array<object or object or object> Required in parent
Minimum items:
1Maximum items:
100requests[] object or object or object Array item
Reference:
#/components/schemas/PromptBulkRequestItemDiscriminator:
{"propertyName":"action","mapping":{"update":"#/components/schemas/PromptBulkUpdateItem","commit":"#/components/schemas/PromptBulkCommitItem","deploy":"#/components/schemas/PromptBulkDeployItem"}}requests[] (oneOf 1) object Schema variant
Reference:
#/components/schemas/PromptBulkUpdateItemAdditional properties are not allowed
requests[] (oneOf 1).prompt_id string Required in parentMinimum length:
1Maximum length:
70requests[] (oneOf 1).action string Required in parent"update"requests[] (oneOf 1).body object Required in parent
Reference:
#/components/schemas/PromptBulkUpdateBodyMinimum properties:
1Additional properties are not allowed
Example:
{"model":"gpt-6-luna","temperature":0.25,"max_tokens":512}requests[] (oneOf 1).body.model string OptionalMaximum length:
70requests[] (oneOf 1).body.stream boolean Optionalrequests[] (oneOf 1).body.temperature number or null Optionalrequests[] (oneOf 1).body.max_tokens integer or null Optionalrequests[] (oneOf 1).body.top_p number or null Optionalrequests[] (oneOf 1).body.frequency_penalty number or null Optionalrequests[] (oneOf 1).body.presence_penalty number or null Optionalrequests[] (oneOf 1).body.reasoning_effort string or null OptionalMaximum length:
70requests[] (oneOf 1).body.verbosity string or null OptionalMaximum length:
50requests[] (oneOf 1).body.thinking any Optionalrequests[] (oneOf 1).body.seed integer or null Optionalrequests[] (oneOf 1).body.tools array<any> or null Optional
requests[] (oneOf 1).body.tools[] any Array itemrequests[] (oneOf 1).body.tool_choice any Optionalrequests[] (oneOf 1).body.response_format any Optionalrequests[] (oneOf 1).body.json_schema any Optionalrequests[] (oneOf 1).body.is_enforcing_response_format boolean Optionalrequests[] (oneOf 2) object Schema variant
Reference:
#/components/schemas/PromptBulkCommitItemAdditional properties are not allowed
requests[] (oneOf 2).prompt_id string Required in parentMinimum length:
1Maximum length:
70requests[] (oneOf 2).action string Required in parent"commit"requests[] (oneOf 2).body object Optional
Reference:
#/components/schemas/PromptBulkCommitBodyAdditional properties are not allowed
Example:
{"description":"Tune production configuration"}requests[] (oneOf 2).body.description string Optionalrequests[] (oneOf 3) object Schema variant
Reference:
#/components/schemas/PromptBulkDeployItemAdditional properties are not allowed
requests[] (oneOf 3).prompt_id string Required in parentMinimum length:
1Maximum length:
70requests[] (oneOf 3).action string Required in parent"deploy"requests[] (oneOf 3).body object OptionalMaximum properties:
0Additional properties are not allowed
OpenAPI request schema
{
"$ref": "#/components/schemas/PromptBulkRequest"
}Update, commit, and deploy one prompt
{
"requests": [
{
"prompt_id": "prm_customer_support",
"action": "update",
"body": {
"model": "gpt-6-luna",
"temperature": 0.25,
"max_tokens": 512
}
},
{
"prompt_id": "prm_customer_support",
"action": "commit",
"body": {
"description": "Tune production configuration"
}
},
{
"prompt_id": "prm_customer_support",
"action": "deploy"
}
]
}Examples
Update, commit, and deploy one prompt
Headers
{
"Authorization": "Bearer YOUR_RESPAN_API_KEY"
}Request
{
"requests": [
{
"prompt_id": "prm_customer_support",
"action": "update",
"body": {
"model": "gpt-6-luna",
"temperature": 0.25,
"max_tokens": 512
}
},
{
"prompt_id": "prm_customer_support",
"action": "commit",
"body": {
"description": "Tune production configuration"
}
},
{
"prompt_id": "prm_customer_support",
"action": "deploy"
}
]
}Response
{
"body": {
"success_count": 3,
"error_count": 0,
"errors": []
}
}Responses
200
All prompt operations succeeded.
application/json
$ object Body
Reference:
#/components/schemas/BulkOperationResponseExample:
{"success_count":1,"error_count":0,"errors":[]}success_count integer Required in parentMinimum:
0error_count integer Required in parentMinimum:
0errors array<object> Required in parent
errors[] object Array item
index is zero-based and identifies the corresponding item in the request array.Reference:
#/components/schemas/BulkItemErrorerrors[].index integer Required in parentMinimum:
0errors[].error string Required in parentOpenAPI response schema
{
"$ref": "#/components/schemas/BulkOperationResponse"
}All three operations succeeded
{
"success_count": 3,
"error_count": 0,
"errors": []
}207
Some prompt operations succeeded and some failed. Successful items remain committed.
application/json
$ object Body
Reference:
#/components/schemas/BulkOperationResponseExample:
{"success_count":1,"error_count":0,"errors":[]}success_count integer Required in parentMinimum:
0error_count integer Required in parentMinimum:
0errors array<object> Required in parent
errors[] object Array item
index is zero-based and identifies the corresponding item in the request array.Reference:
#/components/schemas/BulkItemErrorerrors[].index integer Required in parentMinimum:
0errors[].error string Required in parentOpenAPI response schema
{
"$ref": "#/components/schemas/BulkOperationResponse"
}One prompt was not found
{
"success_count": 1,
"error_count": 1,
"errors": [
{
"index": 1,
"error": "Prompt 'prm_missing' not found."
}
]
}400
The request failed validation, or every prompt operation failed.
application/json
$ object or object Body
$ (oneOf 1) object Schema variant
Reference:
#/components/schemas/BulkOperationResponseExample:
{"success_count":1,"error_count":0,"errors":[]}$ (oneOf 1).success_count integer Required in parentMinimum:
0$ (oneOf 1).error_count integer Required in parentMinimum:
0$ (oneOf 1).errors array<object> Required in parent
$ (oneOf 1).errors[] object Array item
index is zero-based and identifies the corresponding item in the request array.Reference:
#/components/schemas/BulkItemError$ (oneOf 1).errors[].index integer Required in parentMinimum:
0$ (oneOf 1).errors[].error string Required in parent$ (oneOf 2) object Schema variant
$ (oneOf 2).requests array<any> Required in parent
$ (oneOf 2).requests[] any Array itemOpenAPI response schema
{
"oneOf": [
{
"$ref": "#/components/schemas/BulkOperationResponse"
},
{
"type": "object",
"required": [
"requests"
],
"properties": {
"requests": {
"type": "array",
"description": "DRF validation errors for the request array.",
"items": {}
}
},
"additionalProperties": true
}
]
}Every operation failed
{
"success_count": 0,
"error_count": 1,
"errors": [
{
"index": 0,
"error": "Prompt 'prm_missing' not found."
}
]
}Update contains a content field
{
"requests": [
{
"body": {
"messages": [
"Unknown field."
]
}
}
]
}No operations supplied
{
"requests": [
"At least 1 request is required."
]
}403
The API key is missing, invalid or expired, or it can’t update prompts.
application/json
$ object Body
detail string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Example
{
"detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}422
The request contains more than 100 prompt operations.
application/json
$ object Body
detail string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Example
{
"detail": "Cannot process more than 100 items at once."
}429
Rate limit exceeded.
application/json
$ object Body
detail string Required in parentretry_after integer OptionalMinimum:
0OpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
},
"retry_after": {
"type": "integer",
"minimum": 0,
"description": "Seconds to wait before retrying, when provided."
}
}
}Example
{
"detail": "Rate limit exceeded",
"retry_after": 30
}OpenAPI source
The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.
OpenAPI operation
{
"summary": "Update, commit, or deploy prompts in bulk",
"operationId": "processPromptBulkOperations",
"tags": [
"Prompts"
],
"description": "Process 1 to 100 prompt operations sequentially in request order using exact `prompt_id` matching. Each item runs in its own transaction, so a failed item is rolled back without undoing successful items. `update` changes model configuration on the latest draft and does not accept content fields such as `messages`, `variables`, or `description`; `commit` snapshots the latest draft; `deploy` promotes the latest committed version. A later duplicate successful `commit` or `deploy` for the same prompt in one request is returned as an indexed error. This endpoint inherits the caller's configured API-key or JWT rate limits; it has no fixed endpoint-specific RPM.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PromptBulkRequest"
},
"examples": {
"updateCommitDeploy": {
"summary": "Update, commit, and deploy one prompt",
"value": {
"requests": [
{
"prompt_id": "prm_customer_support",
"action": "update",
"body": {
"model": "gpt-6-luna",
"temperature": 0.25,
"max_tokens": 512
}
},
{
"prompt_id": "prm_customer_support",
"action": "commit",
"body": {
"description": "Tune production configuration"
}
},
{
"prompt_id": "prm_customer_support",
"action": "deploy"
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "All prompt operations succeeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkOperationResponse"
},
"examples": {
"allSucceeded": {
"summary": "All three operations succeeded",
"value": {
"success_count": 3,
"error_count": 0,
"errors": []
}
}
}
}
}
},
"207": {
"description": "Some prompt operations succeeded and some failed. Successful items remain committed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkOperationResponse"
},
"examples": {
"partialSuccess": {
"summary": "One prompt was not found",
"value": {
"success_count": 1,
"error_count": 1,
"errors": [
{
"index": 1,
"error": "Prompt 'prm_missing' not found."
}
]
}
}
}
}
}
},
"400": {
"description": "The request failed validation, or every prompt operation failed.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/BulkOperationResponse"
},
{
"type": "object",
"required": [
"requests"
],
"properties": {
"requests": {
"type": "array",
"description": "DRF validation errors for the request array.",
"items": {}
}
},
"additionalProperties": true
}
]
},
"examples": {
"allFailed": {
"summary": "Every operation failed",
"value": {
"success_count": 0,
"error_count": 1,
"errors": [
{
"index": 0,
"error": "Prompt 'prm_missing' not found."
}
]
}
},
"invalidUpdateBody": {
"summary": "Update contains a content field",
"value": {
"requests": [
{
"body": {
"messages": [
"Unknown field."
]
}
}
]
}
},
"emptyBatch": {
"summary": "No operations supplied",
"value": {
"requests": [
"At least 1 request is required."
]
}
}
}
}
}
},
"403": {
"description": "The API key is missing, invalid or expired, or it can't update prompts.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
},
"example": {
"detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}
}
}
},
"422": {
"description": "The request contains more than 100 prompt operations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
},
"example": {
"detail": "Cannot process more than 100 items at once."
}
}
}
},
"429": {
"description": "Rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
},
"retry_after": {
"type": "integer",
"minimum": 0,
"description": "Seconds to wait before retrying, when provided."
}
}
},
"example": {
"detail": "Rate limit exceeded",
"retry_after": 30
}
}
}
}
},
"security": [
{
"RespanApiKey": []
},
{
"DashboardJwt": []
}
],
"x-fern-examples": [
{
"name": "Update, commit, and deploy one prompt",
"request": {
"requests": [
{
"prompt_id": "prm_customer_support",
"action": "update",
"body": {
"model": "gpt-6-luna",
"temperature": 0.25,
"max_tokens": 512
}
},
{
"prompt_id": "prm_customer_support",
"action": "commit",
"body": {
"description": "Tune production configuration"
}
},
{
"prompt_id": "prm_customer_support",
"action": "deploy"
}
]
},
"response": {
"body": {
"success_count": 3,
"error_count": 0,
"errors": []
}
},
"headers": {
"Authorization": "Bearer YOUR_RESPAN_API_KEY"
}
}
]
}OpenAPI path metadata
{}Referenced OpenAPI components
{
"schemas": {
"BulkItemError": {
"type": "object",
"description": "An item that failed during a bulk operation. `index` is zero-based and identifies the corresponding item in the request array.",
"required": [
"index",
"error"
],
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"description": "Zero-based index of the failed item in the submitted array."
},
"error": {
"type": "string",
"description": "Error message for the failed item."
}
}
},
"BulkOperationResponse": {
"type": "object",
"description": "Canonical result envelope for a bulk operation.",
"required": [
"success_count",
"error_count",
"errors"
],
"properties": {
"success_count": {
"type": "integer",
"minimum": 0,
"description": "Number of items successfully processed."
},
"error_count": {
"type": "integer",
"minimum": 0,
"description": "Number of items that failed."
},
"errors": {
"type": "array",
"description": "Item-level failures, keyed by zero-based input index.",
"items": {
"$ref": "#/components/schemas/BulkItemError"
}
}
},
"example": {
"success_count": 1,
"error_count": 0,
"errors": []
}
},
"PromptBulkCommitBody": {
"type": "object",
"description": "Optional commit metadata.",
"additionalProperties": false,
"properties": {
"description": {
"type": "string",
"description": "Optional commit message. Blank strings are accepted."
}
},
"example": {
"description": "Tune production configuration"
}
},
"PromptBulkCommitItem": {
"type": "object",
"description": "Commit the prompt's latest draft.",
"required": [
"prompt_id",
"action"
],
"additionalProperties": false,
"properties": {
"prompt_id": {
"type": "string",
"minLength": 1,
"maxLength": 70,
"description": "Exact prompt ID to mutate."
},
"action": {
"type": "string",
"enum": [
"commit"
]
},
"body": {
"$ref": "#/components/schemas/PromptBulkCommitBody"
}
}
},
"PromptBulkDeployItem": {
"type": "object",
"description": "Deploy the prompt's latest committed version.",
"required": [
"prompt_id",
"action"
],
"additionalProperties": false,
"properties": {
"prompt_id": {
"type": "string",
"minLength": 1,
"maxLength": 70,
"description": "Exact prompt ID to mutate."
},
"action": {
"type": "string",
"enum": [
"deploy"
]
},
"body": {
"type": "object",
"description": "If provided, this object must be empty.",
"maxProperties": 0,
"additionalProperties": false
}
}
},
"PromptBulkRequest": {
"type": "object",
"description": "Ordered prompt operations to process.",
"required": [
"requests"
],
"additionalProperties": false,
"properties": {
"requests": {
"type": "array",
"description": "Prompt operations. Error indices refer to this zero-based array.",
"minItems": 1,
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/PromptBulkRequestItem"
}
}
}
},
"PromptBulkRequestItem": {
"description": "One action in a prompt bulk request.",
"oneOf": [
{
"$ref": "#/components/schemas/PromptBulkUpdateItem"
},
{
"$ref": "#/components/schemas/PromptBulkCommitItem"
},
{
"$ref": "#/components/schemas/PromptBulkDeployItem"
}
],
"discriminator": {
"propertyName": "action",
"mapping": {
"update": "#/components/schemas/PromptBulkUpdateItem",
"commit": "#/components/schemas/PromptBulkCommitItem",
"deploy": "#/components/schemas/PromptBulkDeployItem"
}
}
},
"PromptBulkUpdateBody": {
"type": "object",
"description": "Non-empty model configuration changes for the latest draft. Prompt content fields are not accepted.",
"minProperties": 1,
"additionalProperties": false,
"properties": {
"model": {
"type": "string",
"maxLength": 70,
"description": "Primary model for the draft."
},
"stream": {
"type": "boolean",
"description": "Whether gateway responses using this prompt should stream."
},
"temperature": {
"type": "number",
"nullable": true,
"description": "Sampling temperature."
},
"max_tokens": {
"type": "integer",
"nullable": true,
"description": "Maximum output tokens."
},
"top_p": {
"type": "number",
"nullable": true,
"description": "Nucleus-sampling probability mass."
},
"frequency_penalty": {
"type": "number",
"nullable": true,
"description": "Frequency penalty."
},
"presence_penalty": {
"type": "number",
"nullable": true,
"description": "Presence penalty."
},
"reasoning_effort": {
"type": "string",
"maxLength": 70,
"nullable": true,
"description": "Provider-specific reasoning effort."
},
"verbosity": {
"type": "string",
"maxLength": 50,
"nullable": true,
"description": "Provider-specific output verbosity."
},
"thinking": {
"description": "Provider-specific thinking configuration. Any JSON value is accepted."
},
"seed": {
"type": "integer",
"nullable": true,
"description": "Optional deterministic sampling seed."
},
"tools": {
"type": "array",
"nullable": true,
"description": "Tool definitions made available to the model.",
"items": {}
},
"tool_choice": {
"description": "Tool-selection configuration. Any JSON value is accepted."
},
"response_format": {
"description": "Structured response-format configuration. Any JSON value is accepted."
},
"json_schema": {
"description": "JSON schema for structured output. Any JSON value is accepted."
},
"is_enforcing_response_format": {
"type": "boolean",
"description": "Whether to enforce the configured response format."
}
},
"example": {
"model": "gpt-6-luna",
"temperature": 0.25,
"max_tokens": 512
}
},
"PromptBulkUpdateItem": {
"type": "object",
"description": "Update model configuration on the prompt's latest draft.",
"required": [
"prompt_id",
"action",
"body"
],
"additionalProperties": false,
"properties": {
"prompt_id": {
"type": "string",
"minLength": 1,
"maxLength": 70,
"description": "Exact prompt ID to mutate."
},
"action": {
"type": "string",
"enum": [
"update"
]
},
"body": {
"$ref": "#/components/schemas/PromptBulkUpdateBody"
}
}
}
},
"securitySchemes": {
"DashboardJwt": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "Dashboard JWT",
"description": "Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.",
"x-fern-bearer": {
"name": "dashboardJwt",
"env": "RESPAN_DASHBOARD_JWT"
}
},
"RespanApiKey": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "Respan API key",
"description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
"x-fern-bearer": {
"name": "respanApiKey",
"env": "RESPAN_API_KEY"
}
}
}
}