API Guide

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 '{
    "title": "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"

Query a brain

List the public brains, then run a semantic query against one:

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

curl -X POST https://versuno.ai/api/public/brains/BRAIN_ID/query \
  -H "Authorization: Bearer $VERSUNO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "How do I get started?" }'

Brain queries return HTTP 200 with a { success, error, data } envelope, so check success rather than the status code. The brain-level query is metered. See Brains for the full model.

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:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window (50)
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp (ms) when the window resets

Error Handling

The API uses standard HTTP status codes.

Status	Meaning	What to do
`200`	Success	Process the response normally
`400`	Bad Request	Check request body: a required field is missing or invalid
`401`	Unauthorized	Verify your API key is correct and not suspended
`404`	Not Found	The resource doesn’t exist or belongs to another user
`409`	Conflict	The operation conflicts with the current state (e.g. already trashed)
`500`	Server Error	Retry 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

Method	Endpoint	Description
`GET`	`/assets`	List all assets with optional filters
`POST`	`/assets`	Create a new asset
`GET`	`/assets/{assetId}`	Get a single asset
`PATCH`	`/assets/{assetId}/update`	Update an asset
`POST`	`/assets/{assetId}/trash`	Move an asset to trash
`PUT`	`/assets/{assetId}/trash`	Restore an asset from trash
`DELETE`	`/assets/{assetId}/trash`	Permanently delete a trashed asset
`GET`	`/projects`	List all projects
`POST`	`/projects`	Create a project
`GET`	`/assets/{assetId}/versions`	List version history for an asset
`POST`	`/assets/{assetId}/versions`	Save a version checkpoint
`POST`	`/assets/{assetId}/versions/{versionId}/revert`	Revert to a version
`GET`	`/brains/public`	List public brains
`GET`	`/brains/{id}`	Get a brain
`GET`	`/brains/{id}/containers`	List a brain’s containers
`GET`	`/brains/{id}/nodes/{nodeId}`	Get a single node
`POST`	`/brains/{id}/query`	Semantic query over a brain (metered)

Check the API Reference for complete endpoint documentation with interactive examples, full request/response schemas, and parameter descriptions.

Getting Started

Agents

Memory

Public Brains

Prompt Manager

Authentication

Base URL

Quick Start

List your assets

Create an asset

Save a version checkpoint

Revert to a previous version

Query a brain

Rate Limits

Error Handling

Error response format

Key Endpoints

​Authentication

​Base URL

​Quick Start

​List your assets

​Create an asset

​Save a version checkpoint

​Revert to a previous version

​Query a brain

​Rate Limits

​Error Handling

​Error response format

​Key Endpoints

Authentication

Base URL

Quick Start

List your assets

Create an asset

Save a version checkpoint

Revert to a previous version

Query a brain

Rate Limits

Error Handling

Error response format

Key Endpoints