# List or search bot templates (/docs/api-reference/api/v1/bots/get)

`GET https://mmb-blurware-alpha.vercel.app/api/v1/bots`

List or search bot templates

Bearer auth is optional: keyless requests work at a lower rate limit. With q set, returns full-text matches and no cursor.

Operation ID: `searchBots`

OpenAPI document: https://mmb-blurware-alpha.vercel.app/openapi.json

## Authentication

Optional bearer token: `Authorization: Bearer $MMB_API_KEY`. Public bot templates also accept keyless requests at a lower rate limit.

## Request

### Query parameters

```json
[
  {
    "schema": {
      "type": "string",
      "description": "Full-text search. When set, pagination is disabled."
    },
    "required": false,
    "description": "Full-text search. When set, pagination is disabled.",
    "name": "q",
    "in": "query"
  },
  {
    "schema": {
      "type": "string",
      "description": "Opaque cursor from a previous response."
    },
    "required": false,
    "description": "Opaque cursor from a previous response.",
    "name": "cursor",
    "in": "query"
  },
  {
    "schema": {
      "type": "number",
      "nullable": true,
      "description": "Page size, 1-100. Defaults to 20."
    },
    "required": false,
    "description": "Page size, 1-100. Defaults to 20.",
    "name": "limit",
    "in": "query"
  }
]
```

## Responses

### `200` — One page of bot templates.

**application/json**

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "description": "Stable identifier used in /api/v1/bots/{slug}."
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "description": "Directory category."
          },
          "who": {
            "type": "string",
            "description": "Who runs this bot."
          },
          "handle": {
            "type": "string",
            "description": "Public handle of the operator."
          },
          "job": {
            "type": "string",
            "description": "What the bot does."
          },
          "templateUrl": {
            "type": "string",
            "description": "Public template link."
          },
          "addedAt": {
            "type": "number",
            "description": "Unix epoch milliseconds."
          }
        },
        "required": [
          "slug",
          "name",
          "who",
          "handle",
          "job",
          "templateUrl",
          "addedAt"
        ]
      }
    },
    "nextCursor": {
      "type": "string",
      "nullable": true
    }
  },
  "required": [
    "data",
    "nextCursor"
  ]
}
```

### `401` — The bearer key does not exist.

**application/json**

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_api_key"
      ],
      "description": "Stable machine-readable error code."
    },
    "message": {
      "type": "string",
      "description": "Human-readable summary."
    },
    "hint": {
      "type": "string",
      "description": "Endpoint path that resolves this error, when one exists."
    }
  },
  "required": [
    "error",
    "message"
  ]
}
```

### `403` — The anonymous key expired or exhausted its quota.

**application/json**

```json
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "key_expired"
          ],
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable summary."
        },
        "hint": {
          "type": "string",
          "description": "Endpoint path that resolves this error, when one exists."
        }
      },
      "required": [
        "error",
        "message"
      ]
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "quota_exhausted"
          ],
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable summary."
        },
        "hint": {
          "type": "string",
          "description": "Endpoint path that resolves this error, when one exists."
        }
      },
      "required": [
        "error",
        "message"
      ]
    }
  ]
}
```

### `429` — Too many requests. Mirrors the Retry-After header.

**application/json**

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "rate_limited"
      ],
      "description": "Stable machine-readable error code."
    },
    "message": {
      "type": "string",
      "description": "Human-readable summary."
    },
    "hint": {
      "type": "string",
      "description": "Endpoint path that resolves this error, when one exists."
    }
  },
  "required": [
    "error",
    "message"
  ]
}
```

### `503` — The gateway is unreachable.

**application/json**

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "service_unavailable"
      ],
      "description": "Stable machine-readable error code."
    },
    "message": {
      "type": "string",
      "description": "Human-readable summary."
    },
    "hint": {
      "type": "string",
      "description": "Endpoint path that resolves this error, when one exists."
    }
  },
  "required": [
    "error",
    "message"
  ]
}
```