---
title: "Update, commit, or deploy prompts in bulk"
method: POST
path: "/api/prompts/bulk/"
tags: ["Prompts"]
---

# Update, commit, or deploy prompts in bulk

`POST /api/prompts/bulk/`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/prompts/bulk/`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

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.

## Request body

- PromptBulkRequest: Ordered prompt operations to process.
  - `requests` PromptBulkRequestItem[], required: Prompt operations. Error indices refer to this zero-based array.
    - union: One action in a prompt bulk request.
      - PromptBulkUpdateItem: Update model configuration on the prompt's latest draft.
        - `prompt_id` string, required: Exact prompt ID to mutate.
        - `action` 'update', required
        - `body` PromptBulkUpdateBody, required: Non-empty model configuration changes for the latest draft. Prompt content fields are not accepted.
          - `model` string: Primary model for the draft.
          - `stream` boolean: Whether gateway responses using this prompt should stream.
          - `temperature` number, nullable: Sampling temperature.
          - `max_tokens` integer, nullable: Maximum output tokens.
          - `top_p` number, nullable: Nucleus-sampling probability mass.
          - `frequency_penalty` number, nullable: Frequency penalty.
          - `presence_penalty` number, nullable: Presence penalty.
          - `reasoning_effort` string, nullable: Provider-specific reasoning effort.
          - `verbosity` string, nullable: Provider-specific output verbosity.
          - `thinking` unknown
          - `seed` integer, nullable: Optional deterministic sampling seed.
          - `fallback_models` string[], nullable: Fallback model identifiers.
          - `load_balance_models` unknown[], nullable: Load-balancing model configurations.
            - unknown
          - `tools` unknown[], nullable: Tool definitions made available to the model.
            - unknown
          - `tool_choice` unknown
          - `response_format` unknown
          - `json_schema` unknown
          - `is_enforcing_response_format` boolean: Whether to enforce the configured response format.
      - PromptBulkCommitItem: Commit the prompt's latest draft.
        - `prompt_id` string, required: Exact prompt ID to mutate.
        - `action` 'commit', required
        - `body` PromptBulkCommitBody: Optional commit metadata.
          - `description` string: Optional commit message. Blank strings are accepted.
      - PromptBulkDeployItem: Deploy the prompt's latest committed version.
        - `prompt_id` string, required: Exact prompt ID to mutate.
        - `action` 'deploy', required
        - `body` object: If provided, this object must be empty.

## Response `200`

All prompt operations succeeded.

- 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` BulkItemError[], required: Item-level failures, keyed by zero-based input index.
    - `index` integer, required: Zero-based index of the failed item in the submitted array.
    - `error` string, required: Error message for the failed item.

## Other responses

- `207`: Some prompt operations succeeded and some failed. Successful items remain committed.
- `400`: The request failed validation, or every prompt operation failed.
- `403`: The API key is missing, invalid or expired, or it can't update prompts.
- `422`: The request contains more than 100 prompt operations.
- `429`: Rate limit exceeded.

## Changes

- **2026-10-21** `c30bcb383ee8`: 4 breaking, 8 info
  - request body became required
  - the `requests` request property's minItems was increased to `1`
  - removed `subschema #1, subschema #2, subschema #3` from the `requests/items/` request property `oneOf` list
  - added `subschema #2` to the response body `oneOf` list for the response status `400`
  - …8 more
- **2026-10-02** `b830b79cfd52`: 1 breaking, 2 info
  - the response's body type changed from no type to `object` for status `403`
  - removed the non-success response with the status `401`
  - added the required property `detail` to the response with the `403` status
- **2026-09-17** `6fa8242da8c2`: 1 warning, 1 info
  - deleted the `header` request parameter `Authorization`
  - the endpoint scheme security `RespanApiKey` was added to the API
- **2026-09-12** `22b868ef3f22`: 1 info
  - api operation id `process-prompt-bulk-operations` removed and replaced with `prompts_processPromptBulkOperations`

[Operation history](https://skmtc.dev/respan/apis/respan-api/changes/api/prompts/bulk/post.md)

---

[API](https://skmtc.dev/respan/apis/respan-api.md) - [All operations](https://skmtc.dev/respan/apis/respan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/respan/apis/respan-api/revisions/900841387635?raw)