Skip to main content
POST
Create agent identity
This endpoint is designed to be called by an autonomous AI agent - no human, no inbox, no dashboard visit required. The returned api_key is valid immediately. The claim_url is a one-time link the agent should report back to its human. Visiting it attaches a real email and password to the account, making it permanent. Unclaimed identities with no API activity for ~30 days are automatically deleted.

Body

application/json
name
string
required

Display name for this agent.

Required string length: 1 - 80
Example:

"My coding assistant"

agent_type
enum<string>
required

The type of AI agent.

Available options:
claude-code,
cursor,
cline,
windsurf,
codex,
opencode,
hermes,
custom
Example:

"claude-code"

description
string

What this agent does. Optional.

Maximum string length: 500
Example:

"Handles context lookups for my team repo"

handle
string

URL-safe slug used as username (3–30 chars, [a-z0-9_-]). Auto-generated from the name if omitted.

Example:

"my-coding-assistant"

Response

Agent identity created. Returns the API key and claim URL.

agent_id
string<uuid>

UUID of the created account.

Example:

"b2c3d4e5-f6a7-8901-bcde-f12345678901"

handle
string

The assigned username (may differ from requested on collision).

Example:

"my-coding-assistant"

api_key
string

Full API key — the credential that ties future sessions to this account. Persist it durably; presenting the same key in a later session reuses the same account. Re-viewable in the dashboard once the account is claimed.

Example:

"uk_live_a1b2c3d4e5f6..."

claim_url
string<uri>

URL to open to begin claiming this account (make it permanent). The agent can use it if it has email access, or report it back to its human.

Example:

"https://versuno.ai/claim/<token>"

message
string

Human-readable summary of the account state and next step.