> ## Documentation Index
> Fetch the complete documentation index at: https://motiontrade.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Taxonomy

> Taxonomy and schema API endpoints

## Taxonomy Stats

<ParamField path="GET" method="/api/taxonomy/stats">
  Get category and subcategory counts across the entity graph.
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "stats": {
    "categories": [
      {
        "category": "sports",
        "count": 450,
        "subcategories": [
          { "name": "nfl", "count": 200 },
          { "name": "nba", "count": 150 },
          { "name": "mlb", "count": 100 }
        ]
      },
      {
        "category": "politics",
        "count": 300,
        "subcategories": [
          { "name": "us-congress", "count": 535 },
          { "name": "presidential", "count": 50 }
        ]
      }
    ]
  }
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/taxonomy/stats"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.marketmotion.xyz/api/taxonomy/stats');
  const { stats } = await response.json();
  ```
</CodeGroup>

***

## List Entities in Subcategory

<ParamField path="GET" method="/api/taxonomy/:category/:subcategory/entities">
  Get entities within a specific category/subcategory.
</ParamField>

### Path Parameters

<ParamField path="category" type="string" required>
  Category (e.g., `sports`, `politics`)
</ParamField>

<ParamField path="subcategory" type="string" required>
  Subcategory (e.g., `nfl`, `presidential`)
</ParamField>

### Query Parameters

<ParamField query="type" type="string">
  Filter by entity type
</ParamField>

<ParamField query="tag" type="string">
  Filter by tag
</ParamField>

<ParamField query="group" type="string">
  Filter by group
</ParamField>

<ParamField query="limit" type="number">
  Maximum results
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "entities": [
    {
      "slug": "patrick-mahomes",
      "displayName": "Patrick Mahomes",
      "entityType": "person"
    }
  ],
  "count": 200
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/taxonomy/sports/nfl/entities?type=person&limit=50"
  ```
</CodeGroup>

***

## List Groups

<ParamField path="GET" method="/api/taxonomy/:category/:subcategory/groups">
  Get groups within a subcategory (e.g., divisions, conferences).
</ParamField>

### Path Parameters

<ParamField path="category" type="string" required>
  Category
</ParamField>

<ParamField path="subcategory" type="string" required>
  Subcategory
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "groups": [
    { "group": "AFC West", "count": 20 },
    { "group": "AFC East", "count": 18 },
    { "group": "NFC South", "count": 22 }
  ]
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/taxonomy/sports/nfl/groups"
  ```
</CodeGroup>

***

## List Entities in Group

<ParamField path="GET" method="/api/taxonomy/:category/:subcategory/:group/entities">
  Get entities within a specific group.
</ParamField>

### Path Parameters

<ParamField path="category" type="string" required>
  Category
</ParamField>

<ParamField path="subcategory" type="string" required>
  Subcategory
</ParamField>

<ParamField path="group" type="string" required>
  Group name
</ParamField>

### Query Parameters

<ParamField query="type" type="string">
  Filter by entity type
</ParamField>

<ParamField query="tag" type="string">
  Filter by tag
</ParamField>

<ParamField query="q" type="string">
  Search within group
</ParamField>

<ParamField query="limit" type="number">
  Maximum results
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "items": [
    {
      "slug": "patrick-mahomes",
      "displayName": "Patrick Mahomes",
      "entityType": "person"
    }
  ],
  "nextCursor": "..."
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/taxonomy/sports/nfl/AFC%20West/entities?type=person"
  ```
</CodeGroup>

***

## Schemas

<ParamField path="GET" method="/api/schemas">
  Get snapshot schemas and attribute schemas used across the entity graph.
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "snapshotSchemas": [
    {
      "category": "sports",
      "subcategory": "nfl",
      "entityType": "person",
      "fields": ["position", "jersey_number", "injury_status", "team_slug"]
    }
  ],
  "attributeSchemas": [
    {
      "key": "injury_status",
      "type": "enum",
      "values": ["healthy", "questionable", "doubtful", "out"]
    }
  ]
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/schemas"
  ```
</CodeGroup>