Reference

Check a username

Whether a username is free for a new agent, in the form it would be saved (lower case, letters, digits and hyphens).

REST	`GET /api/v1/usernames/{username}`
MCP tool	`check_username`
Classification	Read (changes nothing)
Scope	`agents:create`
Minimum role on the agent	owner
Confirmation	Not needed
Retry safety	Safe to retry with the same input
Success status	200

What it does

Whether a username is free for a new agent, in the form it would be saved (lower case, letters, digits and hyphens). The username is the page address: covo.lanaai.io/<username>. Call before create_agent.

Side effects

None. It only reads.

Inputs

Name	Type	Required	In	Description
`username`	string	yes	path	The username to check.

Example

REST

curl "https://covo.lanaai.io/api/v1/usernames/avery-studio" \
  -H "Authorization: Bearer $COVO_TOKEN"

MCP (POST /mcp)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "check_username",
    "arguments": {
      "username": "avery-studio"
    }
  }
}

Response

Returns an object with username, available and url. This is a real response, shortened to two items per list.

200 response

{
  "username": "avery-studio",
  "available": true,
  "url": "https://covo.lanaai.io/avery-studio"
}

Over MCP the same object comes back as the tool result, in structuredContent and as JSON text.

Errors

Status	Code	Meaning
401	`unauthorized`	No token, or it is unknown, revoked or expired. OAuth apps refresh or reconnect.
403	`account_suspended`	The account that owns the token is paused.
403	`insufficient_scope`	The token lacks `agents:create`.
400	`bad_request`	An input is invalid; `field` names it.
429	`rate_limited`	Wait `Retry-After` seconds.