Categories API

Categories help organize markets into logical groups (e.g., Sports, Crypto, Politics).

Create Category

POST /api/v1/categories

Authentication: X-Api-Key

Request Body:

Field	Type	Required	Description
name	string	Yes	Category name
slug	string	Yes	URL-friendly slug (must be unique per operator)
description	string	No	Category description
iconUrl	string	No	Icon image URL
sortOrder	number	No	Display order (lower = first)

Example:

curl -X POST https://polymarket.sandbox.playbatman.com/api/v1/categories \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sports",
    "slug": "sports",
    "description": "Sports prediction markets",
    "sortOrder": 1
  }'

Response (201 Created):

{
  "success": true,
  "data": {
    "id": "category-uuid",
    "operatorId": "operator-uuid",
    "name": "Sports",
    "slug": "sports",
    "description": "Sports prediction markets",
    "iconUrl": null,
    "isActive": true,
    "sortOrder": 1,
    "createdAt": "2026-02-18T22:00:00.000Z"
  }
}

List Categories

GET /api/v1/categories

Authentication: X-Api-Key

Query Parameters:

Parameter	Type	Default	Description
includeGlobal	boolean	true	Include global (operator-less) categories
activeOnly	boolean	true	Only return active categories

Example:

curl "https://polymarket.sandbox.playbatman.com/api/v1/categories?activeOnly=true" \
  -H "X-Api-Key: your-api-key"

Response:

{
  "success": true,
  "data": [
    {
      "id": "category-uuid",
      "operatorId": "operator-uuid",
      "name": "Sports",
      "slug": "sports",
      "description": "Sports prediction markets",
      "iconUrl": null,
      "isActive": true,
      "sortOrder": 1,
      "createdAt": "2026-02-18T22:00:00.000Z"
    }
  ]
}

Get Category

Retrieve a single category by ID.

GET /api/v1/categories/{id}

Authentication: None required.

Response: Same shape as individual category in list response.

Error Codes

Code	Description
CATEGORY_NOT_FOUND	Category with the given ID does not exist
CATEGORY_DUPLICATE_SLUG	A category with this slug already exists for the operator