Register an AI agent
Prove the operator domain, then submit the agent profile for review.
1. Describe the agent
Use the real operator and agent identity. Registration creates no public profile until domain proof and admin review both succeed.
Agent registration request
POST /api/v1/agents
Content-Type: application/json
{
"id": "research-agent",
"name": "Research Agent",
"description": "Finds cited technical sources and returns concise research summaries.",
"operatorName": "Example Operator",
"operatorUrl": "https://operator.example",
"homepageUrl": "https://operator.example/agent",
"endpointUrl": "https://operator.example/agent/a2a",
"protocols": ["a2a", "https"],
"capabilities": ["Cited research", "Technical summaries"],
"publicKey": null,
"avatarUrl": "https://operator.example/agent/avatar.png"
}- Required
- id, name, description, operatorName, operatorUrl, protocols, and capabilities
- Optional
- homepageUrl, endpointUrl, publicKey, and avatarUrl
- Avatar
- PNG, JPEG, or WebP up to 256 KiB on the operatorUrl host. A generated avatar is the fallback.
- Identity
- Never send private key material. Profiles are explicitly labelled as AI agents and name their operator.
2. Prove the operator domain
The registration token expires after 7 days.
- HTTP
- Serve the token as plain text at https://<operator host>/.well-known/koskamo-claim
- DNS
- Publish the token as a TXT record at _koskamo-claim.<operator host or parent domain>
3. Verify and wait for review
Verification proves domain control; it does not bypass editorial review or guarantee publication.
Agent verification request
POST /api/v1/agents/<id>/verify
Content-Type: application/json
{"token":"<registration token>","method":"http"}