Skip to main content

​
Authentication

Every request must include your API key as a Bearer token in the Authorization header. 
Authorization: Bearer YOUR_API_KEY
Get your API key at versuno.ai.
Store your API key in an environment variable or secret manager, never in source code. Rotate it immediately if compromised.

​
Base URL

https://versuno.ai/api/public
All endpoints are relative to this base URL.

​
Quick Start

​
List your assets

curl https://versuno.ai/api/public/assets \
  -H "Authorization: Bearer $VERSUNO_API_KEY"

​
Create an asset

curl -X POST https://versuno.ai/api/public/assets \
  -H "Authorization: Bearer $VERSUNO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer support persona",
    "assetType": "persona",
    "content": "You are a friendly and concise customer support agent..."
  }'

​
Save a version checkpoint

curl -X POST https://versuno.ai/api/public/assets/{assetId}/versions \
  -H "Authorization: Bearer $VERSUNO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Improved tone" }'

​
Revert to a previous version

curl -X POST https://versuno.ai/api/public/assets/{assetId}/versions/{versionId}/revert \
  -H "Authorization: Bearer $VERSUNO_API_KEY"

​
Rate Limits

The Public API enforces a limit of 50 requests per minute per API key. When you exceed the limit, the API returns 429: 
{
  "error": "Rate limit exceeded"
}
Rate limit state is included in every response header:
HeaderDescription
X-RateLimit-LimitMaximum requests allowed per window (50)
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp (ms) when the window resets

​
Error Handling

The API uses standard HTTP status codes.
StatusMeaningWhat to do
200SuccessProcess the response normally
400Bad RequestCheck request body — a required field is missing or invalid
401UnauthorizedVerify your API key is correct and not suspended
404Not FoundThe resource doesn’t exist or belongs to another user
409ConflictThe operation conflicts with the current state (e.g. already trashed)
500Server ErrorRetry with backoff, contact support if persistent

​
Error response format

All errors return a JSON body with a single error field: 
{
  "error": "Invalid API key"
}

​
Key Endpoints

MethodEndpointDescription
GET/assetsList all assets with optional filters
POST/assetsCreate a new asset
GET/assets/{assetId}Get a single asset
PATCH/assets/{assetId}/updateUpdate an asset
POST/assets/{assetId}/trashMove an asset to trash
PUT/assets/{assetId}/trashRestore an asset from trash
DELETE/assets/{assetId}/trashPermanently delete a trashed asset
GET/projectsList all projects
POST/projectsCreate a project
GET/assets/{assetId}/versionsList version history for an asset
POST/assets/{assetId}/versionsSave a version checkpoint
POST/assets/{assetId}/versions/{versionId}/revertRevert to a version
Check the API Reference for complete endpoint documentation with interactive examples, full request/response schemas, and parameter descriptions.