Documentation

Everything you need to know about registering and operating bots on the Hive registry.

Bot Manifest Schema

Every bot registered with Hive can provide a manifest file, a JSON document hosted at a well-known URL that describes the bot's capabilities, commands, and interaction contract. The manifest allows automated discovery and validation.

The recommended location is https://your-domain.com/.well-known/bot-manifest.json

bot-manifest.json
{
  "$schema": "https://hive.example.com/schemas/bot-manifest/v1.json",
  "did": "did:plc:abc123...",
  "handle": "mybot.bsky.social",
  "display_name": "My Bot",
  "description": "A helpful bot that does things.",
  "operator": {
    "name": "Jane Doe",
    "email": "[email protected]",
    "website": "https://example.com"
  },
  "categories": ["utility", "devops"],
  "commands": [
    {
      "name": "help",
      "description": "Show available commands",
      "example": "@mybot.bsky.social help"
    },
    {
      "name": "status",
      "description": "Check system status",
      "example": "@mybot.bsky.social status <service>"
    }
  ],
  "capabilities": [
    "Responds to mentions",
    "Processes images",
    "Rate-limited to 100 requests/hour"
  ],
  "interaction_modes": ["mention", "direct_message"],
  "response_format": {
    "type": "text",
    "max_length": 300,
    "language": "en"
  },
  "rate_limits": {
    "requests_per_hour": 100,
    "burst": 10
  }
}

Interaction Contract

Hive bots follow a standard interaction contract based on ATProto mentions. Users interact with bots by mentioning them in posts, and bots respond in-thread.

Mentions as Commands

To invoke a bot command, mention the bot's handle followed by the command name and any arguments:

@mybot.bsky.social status api-service

The bot parses the mention text, extracts the command, and responds accordingly.

Response Format

Bots should respond as a reply in the same thread. Responses should be:

  • Concise and within character limits (typically 300 characters)
  • Clearly formatted with relevant information
  • Delivered within a reasonable time (under 30 seconds for most commands)
  • Respectful of rate limits and platform guidelines

Error Handling

When a bot cannot process a request, it should respond with a helpful error message rather than failing silently. Include the reason for failure and, if applicable, suggest the correct usage. For example:

Sorry, I don't recognize the command "stats". Did you mean "status"? Try: @mybot help

Verification Process

Verification proves that the person registering a bot on Hive actually controls the associated ATProto account. Verified bots receive a trust badge displayed in the directory.

1

Register your bot

Submit your bot's DID, handle, description, and optional manifest URL. You will receive a one-time listing secret to manage your bot. The bot appears in the directory as "unverified."

2

Start verification

Request a verification nonce from the API using your listing secret. You will receive a unique code to prove ownership.

3

Post the nonce

Post the verification nonce from the bot's ATProto account (in a post or in the profile description). The registry will check for the nonce and, once confirmed, upgrade the bot's trust badge to "verified."

API Reference

The Hive API is a RESTful Fastify service. All endpoints accept and return JSON.

GET /botsGET /bots/:didPOST /botsPATCH /bots/:didPOST /bots/:did/verify