# List or search use cases (/docs/api-reference/api/v1/usecases/get)

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

List or search use cases

Public and free. An optional bearer key enables account usage tracking. With q set, returns full-text matches and no cursor.

Operation ID: `searchUsecases`

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 use cases.

**application/json**

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "description": "Stable identifier used in /api/v1/usecases/{slug}."
          },
          "guide": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string"
              },
              "category": {
                "type": "string"
              },
              "opportunity": {
                "type": "string"
              },
              "audience": {
                "type": "string"
              },
              "platforms": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "botSlugs": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "steps": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "prompt": {
                "type": "string"
              },
              "value": {
                "type": "object",
                "properties": {
                  "amount": {
                    "type": "string"
                  },
                  "label": {
                    "type": "string"
                  },
                  "basis": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "reported",
                      "illustrative"
                    ]
                  }
                },
                "required": [
                  "amount",
                  "label",
                  "basis",
                  "kind"
                ],
                "description": "USD inspiration value, explicitly labeled as a creator report or illustrative assumption; not promised earnings."
              }
            },
            "required": [
              "title",
              "category",
              "opportunity",
              "audience",
              "platforms",
              "botSlugs",
              "steps",
              "prompt"
            ]
          },
          "title": {
            "type": "string"
          },
          "who": {
            "type": "string",
            "description": "Who ran this use case."
          },
          "handle": {
            "type": "string",
            "description": "Public handle of the operator."
          },
          "roi": {
            "type": "string",
            "description": "Reported outcome or return."
          },
          "sourceUrl": {
            "type": "string",
            "description": "Public source for the claim."
          },
          "addedAt": {
            "type": "number",
            "description": "Unix epoch milliseconds."
          }
        },
        "required": [
          "slug",
          "title",
          "who",
          "handle",
          "roi",
          "sourceUrl",
          "addedAt"
        ]
      }
    },
    "nextCursor": {
      "type": "string",
      "nullable": true
    }
  },
  "required": [
    "data",
    "nextCursor"
  ]
}
```

### `401` — An account API key is required.

**application/json**

```json
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "unauthorized"
          ],
          "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": [
            "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` — Claim the key or check its quota.

**application/json**

```json
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "enum": [
            "claim_required"
          ],
          "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": [
            "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"
  ]
}
```