> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://respan.ai/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server. # Update, commit, or deploy prompts in bulk POST https://api.respan.ai/api/prompts/bulk/ Content-Type: application/json 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. Reference: https://respan.ai/docs/apis/prompts/update-commit-or-deploy-prompts-in-bulk ## Authentication - `Authorization` header (bearer token, required) — Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer \. 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. - `Authorization` header (bearer token, required) — Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead. ## Request ### Body (application/json) This endpoint expects a PromptBulkRequest. - `requests` (list of PromptBulkRequestItem, required) — Prompt operations. Error indices refer to this zero-based array. ## Response ### 200 All prompt operations succeeded. - `success_count` (integer, required) — Number of items successfully processed. - `error_count` (integer, required) — Number of items that failed. - `errors` (list of BulkItemError, required) — Item-level failures, keyed by zero-based input index. ### 207 Some prompt operations succeeded and some failed. Successful items remain committed. - `success_count` (integer, required) — Number of items successfully processed. - `error_count` (integer, required) — Number of items that failed. - `errors` (list of BulkItemError, required) — Item-level failures, keyed by zero-based input index. ## Errors ### 400 Bad Request Error The request failed validation, or every prompt operation failed. - `ProcessPromptBulkOperationsRequestBadRequestError` ### 403 Forbidden Error The API key is missing, invalid or expired, or it can't update prompts. - `detail` (string, required) ### 422 Unprocessable Entity Error The request contains more than 100 prompt operations. - `detail` (string, required) ### 429 Too Many Requests Error Rate limit exceeded. - `detail` (string, required) - `retry_after` (integer, optional) — Seconds to wait before retrying, when provided. ## Types ### PromptBulkRequestItem One action in a prompt bulk request. - `action`: `update` (update) - `body` (PromptBulkUpdateBody, required) — Non-empty model configuration changes for the latest draft. Prompt content fields are not accepted. - `prompt_id` (string, required) — Exact prompt ID to mutate. - `action`: `commit` (commit) - `prompt_id` (string, required) — Exact prompt ID to mutate. - `body` (PromptBulkCommitBody, optional) — Optional commit metadata. - `action`: `deploy` (deploy) - `prompt_id` (string, required) — Exact prompt ID to mutate. - `body` (PromptBulkRequestItemDiscriminatorMappingDeployBody, optional) — If provided, this object must be empty. ### BulkItemError An item that failed during a bulk operation. `index` is zero-based and identifies the corresponding item in the request array. - `index` (integer, required) — Zero-based index of the failed item in the submitted array. - `error` (string, required) — Error message for the failed item. ### BulkOperationResponse Canonical result envelope for a bulk operation. - `success_count` (integer, required) — Number of items successfully processed. - `error_count` (integer, required) — Number of items that failed. - `errors` (list of BulkItemError, required) — Item-level failures, keyed by zero-based input index. ### ProcessPromptBulkOperationsRequestBadRequestError1 - `requests` (list of any, required) — DRF validation errors for the request array. ### PromptBulkUpdateBody Non-empty model configuration changes for the latest draft. Prompt content fields are not accepted. - `model` (string, optional) — Primary model for the draft. - `stream` (boolean, optional) — Whether gateway responses using this prompt should stream. - `temperature` (double, optional, nullable) — Sampling temperature. - `max_tokens` (integer, optional, nullable) — Maximum output tokens. - `top_p` (double, optional, nullable) — Nucleus-sampling probability mass. - `frequency_penalty` (double, optional, nullable) — Frequency penalty. - `presence_penalty` (double, optional, nullable) — Presence penalty. - `reasoning_effort` (string, optional, nullable) — Provider-specific reasoning effort. - `verbosity` (string, optional, nullable) — Provider-specific output verbosity. - `thinking` (any, optional) — Provider-specific thinking configuration. Any JSON value is accepted. - `seed` (integer, optional, nullable) — Optional deterministic sampling seed. - `fallback_models` (list of string, optional, nullable) — Fallback model identifiers. - `load_balance_models` (list of any, optional, nullable) — Load-balancing model configurations. - `tools` (list of any, optional, nullable) — Tool definitions made available to the model. - `tool_choice` (any, optional) — Tool-selection configuration. Any JSON value is accepted. - `response_format` (any, optional) — Structured response-format configuration. Any JSON value is accepted. - `json_schema` (any, optional) — JSON schema for structured output. Any JSON value is accepted. - `is_enforcing_response_format` (boolean, optional) — Whether to enforce the configured response format. ### PromptBulkCommitBody Optional commit metadata. - `description` (string, optional) — Optional commit message. Blank strings are accepted. ### PromptBulkRequestItemDiscriminatorMappingDeployBody If provided, this object must be empty. ## Examples **Request** ```json { "requests": [ { "action": "update", "body": { "model": "gpt-4o-mini", "temperature": 0.25, "max_tokens": 512 }, "prompt_id": "prm_customer_support" }, { "action": "commit", "prompt_id": "prm_customer_support", "body": { "description": "Tune production configuration" } }, { "action": "deploy", "prompt_id": "prm_customer_support" } ] } ``` **Response** ```json { "success_count": 3, "error_count": 0, "errors": [] } ``` **SDK Code** ```python import requests url = "https://api.respan.ai/api/prompts/bulk/" payload = { "requests": [ { "action": "update", "body": { "model": "gpt-4o-mini", "temperature": 0.25, "max_tokens": 512 }, "prompt_id": "prm_customer_support" }, { "action": "commit", "prompt_id": "prm_customer_support", "body": { "description": "Tune production configuration" } }, { "action": "deploy", "prompt_id": "prm_customer_support" } ] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.respan.ai/api/prompts/bulk/'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"requests":[{"action":"update","body":{"model":"gpt-4o-mini","temperature":0.25,"max_tokens":512},"prompt_id":"prm_customer_support"},{"action":"commit","prompt_id":"prm_customer_support","body":{"description":"Tune production configuration"}},{"action":"deploy","prompt_id":"prm_customer_support"}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.respan.ai/api/prompts/bulk/" payload := strings.NewReader("{\n \"requests\": [\n {\n \"action\": \"update\",\n \"body\": {\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.25,\n \"max_tokens\": 512\n },\n \"prompt_id\": \"prm_customer_support\"\n },\n {\n \"action\": \"commit\",\n \"prompt_id\": \"prm_customer_support\",\n \"body\": {\n \"description\": \"Tune production configuration\"\n }\n },\n {\n \"action\": \"deploy\",\n \"prompt_id\": \"prm_customer_support\"\n }\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.respan.ai/api/prompts/bulk/") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"requests\": [\n {\n \"action\": \"update\",\n \"body\": {\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.25,\n \"max_tokens\": 512\n },\n \"prompt_id\": \"prm_customer_support\"\n },\n {\n \"action\": \"commit\",\n \"prompt_id\": \"prm_customer_support\",\n \"body\": {\n \"description\": \"Tune production configuration\"\n }\n },\n {\n \"action\": \"deploy\",\n \"prompt_id\": \"prm_customer_support\"\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.respan.ai/api/prompts/bulk/") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"requests\": [\n {\n \"action\": \"update\",\n \"body\": {\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.25,\n \"max_tokens\": 512\n },\n \"prompt_id\": \"prm_customer_support\"\n },\n {\n \"action\": \"commit\",\n \"prompt_id\": \"prm_customer_support\",\n \"body\": {\n \"description\": \"Tune production configuration\"\n }\n },\n {\n \"action\": \"deploy\",\n \"prompt_id\": \"prm_customer_support\"\n }\n ]\n}") .asString(); ``` ```php request('POST', 'https://api.respan.ai/api/prompts/bulk/', [ 'body' => '{ "requests": [ { "action": "update", "body": { "model": "gpt-4o-mini", "temperature": 0.25, "max_tokens": 512 }, "prompt_id": "prm_customer_support" }, { "action": "commit", "prompt_id": "prm_customer_support", "body": { "description": "Tune production configuration" } }, { "action": "deploy", "prompt_id": "prm_customer_support" } ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.respan.ai/api/prompts/bulk/"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"requests\": [\n {\n \"action\": \"update\",\n \"body\": {\n \"model\": \"gpt-4o-mini\",\n \"temperature\": 0.25,\n \"max_tokens\": 512\n },\n \"prompt_id\": \"prm_customer_support\"\n },\n {\n \"action\": \"commit\",\n \"prompt_id\": \"prm_customer_support\",\n \"body\": {\n \"description\": \"Tune production configuration\"\n }\n },\n {\n \"action\": \"deploy\",\n \"prompt_id\": \"prm_customer_support\"\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["requests": [ [ "action": "update", "body": [ "model": "gpt-4o-mini", "temperature": 0.25, "max_tokens": 512 ], "prompt_id": "prm_customer_support" ], [ "action": "commit", "prompt_id": "prm_customer_support", "body": ["description": "Tune production configuration"] ], [ "action": "deploy", "prompt_id": "prm_customer_support" ] ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.respan.ai/api/prompts/bulk/")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```