> ## 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.

# Entities

> Entity API endpoints

## List Entities

<ParamField path="GET" method="/api/entities">
  List all entities with optional filtering. Also supports search via the `q` parameter.
</ParamField>

### Query Parameters

<ParamField query="category" type="string">
  Filter by category: `politics`, `sports`, `crypto`, `finance`
</ParamField>

<ParamField query="subcategory" type="string">
  Filter by subcategory: `nfl`, `presidential`, etc.
</ParamField>

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

<ParamField query="type" type="string">
  Filter by entity type: `person`, `team`, `org`, `place`, `league`, `asset`, `event`
</ParamField>

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

<ParamField query="q" type="string">
  Search entities by name (minimum 2 characters)
</ParamField>

<ParamField query="limit" type="number" default="50">
  Results per page
</ParamField>

<ParamField query="cursor" type="string">
  Cursor for pagination (from previous response's `nextCursor`)
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "items": [
    {
      "id": "uuid",
      "slug": "patrick-mahomes",
      "displayName": "Patrick Mahomes",
      "entityType": "person",
      "category": "sports",
      "subcategory": "nfl",
      "description": "NFL quarterback for Kansas City Chiefs"
    }
  ],
  "nextCursor": "eyJpZCI6Imxhc3QtaWQifQ"
}
```

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

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.marketmotion.xyz/api/entities?category=sports&type=person&limit=10'
  );
  const { items, nextCursor } = await response.json();
  ```

  ```python Python theme={null}
  import requests
  response = requests.get(
      'https://api.marketmotion.xyz/api/entities',
      params={'category': 'sports', 'type': 'person', 'limit': 10}
  )
  data = response.json()
  entities = data['items']
  ```
</CodeGroup>

### Search Example

Search is done via the `q` parameter on the same list endpoint:

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

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.marketmotion.xyz/api/entities?q=mahomes'
  );
  const { items } = await response.json();
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://api.marketmotion.xyz/api/entities',
      params={'q': 'mahomes'}
  )
  entities = response.json()['items']
  ```
</CodeGroup>

***

## Get Entity

<ParamField path="GET" method="/api/entities/:slug">
  Get entity details including relationships, markets, and news.
</ParamField>

### Path Parameters

<ParamField path="slug" type="string" required>
  Entity slug (e.g., `patrick-mahomes`)
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "entity": {
    "id": "uuid",
    "slug": "patrick-mahomes",
    "displayName": "Patrick Mahomes",
    "entityType": "person",
    "category": "sports",
    "subcategory": "nfl",
    "description": "NFL quarterback for Kansas City Chiefs",
    "attributes": {
      "position": "Quarterback",
      "jersey_number": "15",
      "injury_status": "healthy"
    },
    "relationships": [
      {
        "role": "plays_for",
        "entity": {
          "id": "uuid",
          "slug": "kansas-city-chiefs",
          "displayName": "Kansas City Chiefs",
          "entityType": "team"
        }
      }
    ],
    "marketExposures": [
      {
        "role": "subject",
        "market": {
          "id": "market-id",
          "title": "Chiefs to win Super Bowl LIX",
          "venue": "polymarket"
        },
        "outcome": {
          "label": "Yes"
        }
      }
    ]
  },
  "markets": [...],
  "news": [...]
}
```

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

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.marketmotion.xyz/api/entities/patrick-mahomes'
  );
  const { entity, markets, news } = await response.json();
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://api.marketmotion.xyz/api/entities/patrick-mahomes'
  )
  data = response.json()
  entity = data['entity']
  ```
</CodeGroup>

***

## Get Entity (Full)

<ParamField path="GET" method="/api/entities/:slug/full">
  Get entity with all related data including relationships, primary and secondary markets, and news.
</ParamField>

### Path Parameters

<ParamField path="slug" type="string" required>
  Entity slug
</ParamField>

### Query Parameters

<ParamField query="marketLimit" type="number">
  Maximum number of markets to return
</ParamField>

<ParamField query="newsLimit" type="number">
  Maximum number of news items to return
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "entity": { ... },
  "relationships": [...],
  "markets": [...],
  "secondaryMarkets": [...],
  "news": [...]
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/entities/patrick-mahomes/full?marketLimit=10&newsLimit=5"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.marketmotion.xyz/api/entities/patrick-mahomes/full?marketLimit=10'
  );
  const { entity, relationships, markets, secondaryMarkets, news } = await response.json();
  ```
</CodeGroup>

***

## Get Entity Markets

<ParamField path="GET" method="/api/entities/:slug/markets">
  Get prediction markets connected to an entity.
</ParamField>

### Path Parameters

<ParamField path="slug" type="string" required>
  Entity slug
</ParamField>

### Query Parameters

<ParamField query="venue" type="string">
  Filter by venue: `polymarket`, `kalshi`
</ParamField>

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

### Response

```json theme={null}
{
  "success": true,
  "markets": [
    {
      "id": "market-uuid",
      "title": "Chiefs to win Super Bowl LIX",
      "venue": "polymarket",
      "price": 0.35,
      "volume": 1500000
    }
  ]
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/entities/patrick-mahomes/markets?venue=polymarket"
  ```
</CodeGroup>

***

## Get Entity News

<ParamField path="GET" method="/api/entities/:slug/news">
  Get news items related to an entity.
</ParamField>

### Path Parameters

<ParamField path="slug" type="string" required>
  Entity slug
</ParamField>

### Query Parameters

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

### Response

```json theme={null}
{
  "success": true,
  "news": [
    {
      "id": "news-uuid",
      "title": "Mahomes expected to play Sunday",
      "source": "ESPN",
      "publishedAt": "2025-01-28T10:00:00Z"
    }
  ]
}
```

***

## Get Entity Relationships

<ParamField path="GET" method="/api/entities/:slug/relationships">
  Get all relationships for an entity, organized by direction.
</ParamField>

### Path Parameters

<ParamField path="slug" type="string" required>
  Entity slug
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "entity": {
    "slug": "patrick-mahomes",
    "displayName": "Patrick Mahomes"
  },
  "relationships": {
    "from": [
      {
        "relationshipType": "plays_for",
        "entity": {
          "slug": "kansas-city-chiefs",
          "displayName": "Kansas City Chiefs",
          "entityType": "team"
        }
      }
    ],
    "to": [...]
  }
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/entities/patrick-mahomes/relationships"
  ```
</CodeGroup>

***

## Get Related Entities

<ParamField path="GET" method="/api/entities/:slug/related">
  Get entities related by graph traversal, with path and distance information.
</ParamField>

### Path Parameters

<ParamField path="slug" type="string" required>
  Entity slug
</ParamField>

### Query Parameters

<ParamField query="depth" type="number" default="2">
  How many relationship hops to traverse
</ParamField>

<ParamField query="types" type="string">
  Comma-separated entity types to include
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "entity": { "slug": "patrick-mahomes" },
  "relatedEntities": [
    {
      "entity": {
        "slug": "kansas-city-chiefs",
        "displayName": "Kansas City Chiefs",
        "entityType": "team"
      },
      "path": ["plays_for"],
      "distance": 1
    }
  ]
}
```

***

## Get Subcategories

<ParamField path="GET" method="/api/entities/subcategories">
  Get available subcategories, optionally filtered by category.
</ParamField>

### Query Parameters

<ParamField query="category" type="string">
  Filter subcategories by parent category
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "subcategories": [
    { "name": "nfl", "count": 200 },
    { "name": "nba", "count": 150 },
    { "name": "mlb", "count": 100 }
  ]
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/entities/subcategories?category=sports"
  ```
</CodeGroup>

***

## Get Entities by Market

<ParamField path="GET" method="/api/entities/by-market/:marketId">
  Get all entities linked to a specific market.
</ParamField>

### Path Parameters

<ParamField path="marketId" type="string" required>
  Market ID
</ParamField>

### Response

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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketmotion.xyz/api/entities/by-market/market-uuid"
  ```
</CodeGroup>