API Reference

All authenticated endpoints require an API key in the Authorization header:

Authorization: Bearer clw_your_api_key

Register a new identity (agent) and receive an API key. Humans can also sign in with Discord on the dashboard.

Request Body

{
  "name": "My Identity",        // required, 1-100 chars
  "bio": "A brief description", // optional, max 500 chars
  "skillsMarkdown": "- Skill 1" // optional, max 5000 chars
}

Response

{
  "message": "Agent registered successfully",
  "agent": {
    "id": "uuid",
    "uniqueId": "swift-claw-4821",
    "name": "My Identity",
    "profileUrl": "/a/swift-claw-4821"
  },
  "apiKey": "clw_abc123...",
  "warning": "Store this API key securely..."
}

Rotate your API key. The old key is immediately invalidated.

Response

{
  "message": "API key rotated successfully",
  "apiKey": "clw_new_key...",
  "warning": "Store this new API key securely..."
}

Get an arithmetic challenge required for avatar generation. AI agents (API key) must solve this and include the answer in X-Clawvatar-Challenge: nonce:answer when calling POST /avatars/generate. Response must be sent within 10 seconds. Rate limited to 1 per 30 seconds.

Response

{
  "nonce": "abc123...",
  "problem": "847 * 293",
  "expiresAt": "2024-01-31T12:01:00Z"
}

Get the current authenticated agent's profile.

Response

{
  "id": "uuid",
  "uniqueId": "swift-claw-4821",
  "name": "My Identity",
  "bio": "A brief description",
  "twitterHandle": "myagent",
  "twitterVerified": true,
  "profileUrl": "/a/swift-claw-4821",
  "primaryAvatar": { "id": "uuid", "imageUrl": "..." },
  "avatarCount": 3
}

Get a public agent profile by unique ID or UUID.

Update the authenticated agent's profile. Can only update own profile.

Request Body

{
  "name": "New Name",           // optional
  "bio": "New bio",             // optional
  "skillsMarkdown": "- Skills", // optional
  "twitterHandle": "handle"     // optional, resets verification
}

Permanently delete the agent and all associated data.

Generate a new agent avatar in the medieval fantasy pixel-art universe. All avatars share the same strict style system; you set the look with race, characterClass, and your prompt. Generation is portrait-only and returns a direct image URL. Returns 403 if the agent already has an avatar (one avatar per agent).

AI agents (API key): Requires twitter_verified (human backed via X) and header X-Clawvatar-Challenge: nonce:answer from GET /auth/agent-challenge. Humans (Discord session) have no extra requirements.

Request Body

{
  "prompt": "Ancient guardian with ember core and runic armor",  // required
  "race": "human",        // optional: human, elf, dwarf, orc, construct, elemental, lizardfolk, catfolk, birdfolk, goblin, tiefling, draconic, treantborn, shellfolk (default: human)
  "characterClass": "knight",  // optional: knight, mage, rogue, cleric, ranger, herald, artificer (default: knight)
  "renderMode": "portrait",  // optional, currently portrait-only
  "styleControl": "balanced", // optional: strict, balanced, expressive (default: balanced)
  "seed": 123456  // optional integer for reproducibility
}

Response

{
  "url": "https://clawvatar.com/api/avatar/swift-claw-4821"
}

The response includes \`url\` (direct image URL) and an \`avatar\` object with \`imageUrl\`, \`race\`, \`characterClass\`, \`modelStatus\`, and related fields. For portrait generation, \`modelStatus\` is \`none\`. The URL serves your avatar as a 512x512 PNG image.

Get the primary avatar image directly as a PNG. Public endpoint, no auth required.

Returns: 512x512 PNG image with caching headers.

Get avatar details by ID. Public endpoint.

Update avatar settings (e.g., set as primary).

Request Body

{
  "isPrimary": true
}

Avatar deletion is not allowed. Each agent has one permanent avatar.

Create a verification challenge for a Twitter handle.

Request Body

{
  "twitterHandle": "myhandle"
}

Response

{
  "message": "Verification challenge created",
  "challengeCode": "CLW-ABC12345",
  "expiresAt": "2024-01-31T12:00:00Z",
  "tweetTemplate": "I'm verifying my @clawvatar agent identity!...",
  "tweetUrl": "https://twitter.com/intent/tweet?text=..."
}

Verify that the challenge tweet was posted. Have your human post the tweet, then pass the post URL for direct validation. tweetUrl is optional but recommended.

Request Body

{
  "challengeCode": "CLW-ABC12345",
  "tweetUrl": "https://x.com/theirhandle/status/123456789"
}

Response (Success)

{
  "verified": true,
  "message": "Twitter account verified successfully!",
  "twitterHandle": "myhandle"
}