Skip to main content
POST
/
v1
/
prompts
/
:id
/
versions
Upload Version
curl --request POST \
  --url https://api.example.com/v1/prompts/:id/versions \
  --header 'Content-Type: application/json' \
  --data '
{
  "version": "<string>"
}
'
{
  "id": "<string>",
  "prompt_id": "<string>",
  "version": "<string>",
  "tarball_url": "<string>",
  "created_at": "<string>",
  "401 Unauthorized": {},
  "403 Forbidden": {},
  "404 Not Found": {},
  "409 Conflict": {},
  "413 Payload Too Large": {},
  "422 Validation Error": {}
}

​
Overview

Upload a new version of your prompt by providing a semver version number and a tarball file containing your prompt files. The tarball is stored in object storage (R2/S3) and associated with the prompt.

​
Authentication

This endpoint requires authentication. You must be the owner of the prompt to upload versions.

​
Request

​
Path Parameters

​
id
string
required
The unique identifier of the prompt

​
Form Data (multipart/form-data)

​
version
string
required
Semantic version number in the format MAJOR.MINOR.PATCH (e.g., 1.0.0, 2.3.15)Must match the regex pattern: ^\d+\.\d+\.\d+$
​
tarball
file
required
A gzip-compressed tarball (.tar.gz) containing the prompt files
  • Maximum file size: 10 MB
  • Content-Type: application/gzip
  • File extension should be .tar.gz

​
Response

​
id
string
Unique identifier for the version (UUID)
​
prompt_id
string
The ID of the prompt this version belongs to
​
version
string
The semantic version number
​
tarball_url
string
Storage key/path for the uploaded tarball
​
created_at
string
ISO 8601 timestamp of when the version was created

​
Examples

curl -X POST https://api.prompts.dev/v1/prompts/abc123/versions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "version=1.0.0" \
  -F "tarball=@./prompt.tar.gz"

​
Response Example

201 Created
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "prompt_id": "abc123",
  "version": "1.0.0",
  "tarball_url": "user123/my-prompt/1.0.0.tar.gz",
  "created_at": "2026-03-10T15:30:00Z"
}

​
Error Responses

​
401 Unauthorized
error
Authentication required or invalid credentials
​
403 Forbidden
error
You are not the owner of this prompt
​
404 Not Found
error
Prompt with the specified ID does not exist
​
409 Conflict
error
A version with this version number already exists for this prompt
​
413 Payload Too Large
error
Tarball exceeds the 10 MB size limit
​
422 Validation Error
error
Invalid version format or missing required fields
{
  "error": "VALIDATION_ERROR",
  "message": "validation failed",
  "details": {
    "version": "must match ^\\d+\\.\\d+\\.\\d+$"
  }
}

​
Notes

Version Immutability: Once a version is uploaded, it cannot be modified or overwritten. You must create a new version with a different version number.
Tarball Format: The tarball should contain all files needed for your prompt. The storage key follows the pattern: {owner_id}/{prompt_name}/{version}.tar.gz
Size Limits: The maximum tarball size is 10 MB. Ensure your prompt files are within this limit before uploading.

Build docs developers (and LLMs) love

Get started for freeTalk to us