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

# List Categories

> Returns the prediction-market category tree, built from the categories that have at least one active contract.

**Use Case:** Render a category menu, then narrow search to the category a user picks.


## Overview

Every base event carries the venue's categories, broadest first: category, subcategory, then region (see `categoryLevels` on [Get Base Event](/api-reference/predictions/get-base-event)). This endpoint returns those categories as one tree, so you can show them without walking every base event.

```
GET /v1/predictions/categories
```

## Identify a category by its path

Level names repeat under different parents. `United States`, for example, sits under many categories. So each node carries a `path`: every level from the top down to that node, joined by `>`.

| Field | Description |
| - | - |
| `name` | This level's name, for display. |
| `path` | The category's identifier, such as `Elections > United States House`. |
| `children` | The categories one level down. Absent on a leaf. |

Pass a node's `path` unchanged to [Search Prediction Market](/api-reference/predictions/search) as `category`. Search then returns that category and everything under it. Don't build paths yourself; always take them from this endpoint.

## What the tree contains

* Only categories with at least one `ACTIVE` contract. A category whose contracts have all expired or been withdrawn drops out, so every category in the tree finds something when you search it.
* Each level is ordered by name.
* With no active contracts, `categories` is an empty array.

The tree is read from the search index, which trails the catalogue by seconds.

## Response

```json theme={null}
{
  "success": true,
  "data": {
    "categories": [
      {
        "name": "Elections",
        "path": "Elections",
        "children": [
          {
            "name": "United States House",
            "path": "Elections > United States House",
            "children": [
              { "name": "Arizona", "path": "Elections > United States House > Arizona" },
              { "name": "Texas", "path": "Elections > United States House > Texas" }
            ]
          }
        ]
      }
    ]
  }
}
```

## Examples

### List the category tree

```bash theme={null}
curl -X GET "https://api.aries.com/v1/predictions/categories"
```

### Search one category picked from the tree

```bash theme={null}
curl -G "https://api.aries.com/v1/predictions/search" \
  --data-urlencode "category=Elections > United States House" \
  -d type=base-events
```

## Errors

* `502`: the search index was unavailable


## OpenAPI

````yaml openapi.json GET /v1/predictions/categories
openapi: 3.0.3
info:
  contact:
    email: dev@aries.com
    name: Aries Financial
  description: >-
    OpenAPI Specification for the Aries trading platform API.


    # Authentication


    Learn how to authenticate with the Aries API using OAuth2 and manage access
    tokens in your SDK.


    ## Overview


    The Aries API uses **OAuth2 with Bearer tokens** (JWT format) for
    authentication. All API requests require a valid access token in the
    `Authorization` header:


    ```

    Authorization: Bearer <access_token>

    ```


    ## Providing Client ID and Client Secret (SDK)


    When using the generated SDK, provide your **Client ID** and **Client
    Secret** when you create the API client (e.g. in the constructor or security
    options). The SDK will use these to obtain and refresh the access token
    internally; you do not need to manage tokens yourself.


    Obtain your OAuth2 credentials from the Aries platform (e.g. Client Center /
    Manage Account at https://app.aries.com):


    - **Client ID** – Your application identifier (pass to SDK client)

    - **Client Secret** – Your application secret key (pass to SDK client; use
    PKCE for public clients where secret cannot be stored)


    ## Authentication Flow


    ### 1. Authorization Code Flow


    For server-side or confidential clients:


    1. **Redirect the user** to the authorization URL to sign in and consent:
     - **URL:** `https://app.aries.com/oauth2/authorize`
     - **Query params:** `response_type=code`, `client_id`, `redirect_uri`, `scope`, `state`

    2. **Exchange the code for tokens** (after user is redirected back with
    `?code=.`):
     - **POST** `https://api.aries.com/v1/oauth2/token`
     - **Body:** `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`, `client_secret`
     - Response includes `access_token` and `refresh_token`

    3. **Call the API** with the access token: `Authorization: Bearer
    <access_token>`


    ### 2. PKCE Flow


    For SPAs and mobile apps (public clients that cannot store `client_secret`):


    1. Generate a **code_verifier** (random string) and **code_challenge** =
    BASE64URL(SHA256(code_verifier)).

    2. **Redirect the user** to `https://app.aries.com/oauth2/authorize` with
    `code_challenge`, `code_challenge_method=S256`, plus `client_id`,
    `redirect_uri`, `scope`, `state`.

    3. **Exchange the code** at POST `https://api.aries.com/v1/oauth2/token`
    with `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`,
    `code_verifier` (no client_secret).

    4. Use the returned `access_token` as Bearer.


    ### 3. MFA Verification


    If the user has MFA enabled, the authorize step may return `is_mfa: true`
    and a `next_step_auth_id`. Call **POST**
    `https://api.aries.com/v1/oauth2/authorize/mfa` with `next_step_auth_id` and
    `verification_code` (6-digit code). Then continue with **POST**
    `/v1/oauth2/authorize/confirm` to get the authorization code, and exchange
    it at `/v1/oauth2/token`.


    ## Token Management


    - **Refresh when expired:** POST `https://api.aries.com/v1/oauth2/token`
    with `grant_type=refresh_token`, `client_id`, `client_secret`,
    `refresh_token`.

    - **Using a Bearer token directly:** If you already have an access token,
    set the header `Authorization: Bearer <access_token>` on every request. The
    SDK can accept a pre-obtained token and use it until it expires.


    ## OAuth2 Scopes


    Request only the scopes your application needs. Available scopes:


    | Scope | Description |

    |-------|-------------|

    | `user:information` | View user profile and personal details |

    | `watchlist:information` | View your watchlists and their symbols |

    | `watchlist:management` | Create, update, replace, and delete your
    watchlists |

    | `account:information` | View account balances, positions, and transaction
    history |

    | `order:execution` | Place, modify, and cancel orders |

    | `order:information` | View order history and status |

    | `position:information` | View current positions and holdings |

    | `market:information` | Access live and historical market data |

    | `calendar:information` | Access earnings, economic, and market schedule
    data |

    | `options:information` | Access options chains and expiration data |

    | `analytics:information` | View analytics, ratings, and market insights |

    | `market:supplemental` | News, company profiles, financials, filings, ETF
    data, technical analysis |


    Specify multiple scopes as a space-separated string, e.g.
    `account:information order:execution market:information`.


    ## Security Best Practices


    - **Store credentials securely** – Use environment variables or a secrets
    manager for `client_id` and `client_secret`. Never hardcode them.

    - **Handle token expiration** – Check for 401 responses and refresh the
    token using the refresh_token, then retry the request.

    - **Use HTTPS** – All authorization and token endpoints must be called over
    HTTPS.

    - **Validate state** – When using the authorization code flow, validate the
    `state` parameter on the callback to prevent CSRF.


    ## Error Handling


    - **400 Bad Request** – Invalid or missing parameters, validation failures,
    or malformed JSON. Response bodies follow the same patterns as other errors
    (flat `error` string, optional `codes`, nested `error` object, or rarely no
    body).


    - **401 Unauthorized** – Invalid or expired access token; refresh the token
    or re-authenticate. JSON bodies are not identical on every route: you may
    see a flat `error` string (sometimes with `codes`), a nested `error` object
    (`type`, `code`, `message`), or rarely an empty body


    - **403 Forbidden** – Insufficient scope or permissions for the requested
    resource. Error JSON may be flat or nested, like 400/401.


    - **404 Not Found** – Resource does not exist or is not visible. Error JSON
    may be flat or nested.


    - **500 / 5xx** – Server or upstream failure; retry with backoff. Do not
    depend on a single error JSON shape; some responses may have no body.



    ---


    Endpoints in this spec: health, OAuth2 (authorize, confirm, mfa, token),
    users, accounts, orders, market data, watchlist, chart, analytics,
    calendars, company, economy, financials, indices, options, news, and
    supplemental data.
  title: Aries API — OpenAPI Specification
  version: 1.0.0
servers:
  - description: Production
    url: https://api.aries.com
  - description: Staging
    url: https://api.tradearies.dev
security: []
tags:
  - description: Account management endpoints for positions, orders, and balances
    name: Accounts
  - description: >-
      Analytics endpoints for market data analysis including top gainers,
      losers, volume leaders, sector analysis, analyst ratings, market breadth,
      and net inflow
    name: Analytics
  - description: Calendar and mergers/acquisitions endpoints
    name: Calendar
  - description: Chart endpoints for config, symbols, history, quotes, and server time
    name: Chart
  - name: Company
  - description: 'Corporate actions: spinoffs, tender offers, IPO calendar, dividends'
    name: Corporate Actions
  - name: ETF
  - description: 'Economy endpoints: inflation, inflation expectations, treasury yields'
    name: Economy
  - name: Filings
  - description: >-
      Financials: reported, statements, revenue breakdown, short volume, ratios,
      short interest
    name: Financials
  - description: >-
      Indices endpoints for groups, list, search, bar, bars, chart-bars,
      realtime values
    name: Indices
  - description: Logos search and sync endpoints
    name: Logos
  - name: Market
  - description: >-
      Market data endpoints for symbol search, real-time data access, and equity
      details
    name: Market Data
  - description: News and news sentiment endpoints
    name: News
  - description: >-
      Options endpoints: expiry dates, contracts, activity, trades, quotes,
      unusual activity
    name: Options
  - description: >-
      Order management endpoints for placing, updating, canceling, and
      previewing orders
    name: Orders
  - name: Ownership
  - description: Signals and bull-bear cases
    name: Signals
  - description: >-
      Transcripts, company presentation, social sentiment, investment themes,
      supply chain, and ESG data
    name: Stock Alternative
  - name: Stock Estimates
  - name: Stocks
  - name: Technical Analysis
  - description: >-
      Watchlist endpoints for listing, creating, updating, and deleting
      watchlists
    name: Watchlist
  - description: Historical YES/NO tick data for prediction-market contracts
    name: Prediction Historical Data
  - description: >-
      Prediction-market reference data and full-text search over base events,
      events, and contracts
    name: Prediction Market Data
  - description: >-
      Closed beta. Place prediction-market orders and read back the
      authenticated user's order history.
    name: Prediction Orders
paths:
  /v1/predictions/categories:
    get:
      tags:
        - Prediction Market Data
      summary: List prediction market categories
      description: >-
        The category tree of every category with at least one ACTIVE contract,
        so each one finds something when passed to search as category. Each
        level is ordered by name. Read from the search index, which trails the
        catalogue by seconds.
      operationId: listCategories
      responses:
        '200':
          content:
            application/json:
              example:
                data:
                  categories:
                    - children:
                        - children:
                            - name: Arizona
                              path: Elections > United States House > Arizona
                          name: United States House
                          path: Elections > United States House
                      name: Elections
                      path: Elections
                success: true
              schema:
                allOf:
                  - $ref: '#/components/schemas/PredMdSuccessEnvelope'
                  - properties:
                      data:
                        properties:
                          categories:
                            items:
                              $ref: '#/components/schemas/PredMdCategory'
                            type: array
                        required:
                          - categories
                        type: object
                    type: object
          description: The category tree; empty when no contract is active
        '502':
          $ref: '#/components/responses/PredMdBadGateway'
      security: []
components:
  schemas:
    PredMdSuccessEnvelope:
      description: >-
        Standard success envelope used by all success responses. `data` is
        endpoint-specific.
      properties:
        data: {}
        success:
          example: true
          type: boolean
      required:
        - success
      type: object
    PredMdCategory:
      description: One node of the category tree.
      properties:
        children:
          description: The categories one level down, ordered by name. Absent on a leaf.
          items:
            $ref: '#/components/schemas/PredMdCategory'
          type: array
        name:
          description: This level's name, for display.
          example: United States House
          type: string
        path:
          description: >-
            Every level from the top down to this one, joined by " > ". It
            identifies the category and is what search takes as category.
          example: Elections > United States House
          type: string
      required:
        - name
        - path
      type: object
    ErrorEnvelope:
      description: >-
        Prediction-market error envelope. Returned by historical-data and
        prediction-market reference endpoints on 400/404/500/502.
      properties:
        error:
          $ref: '#/components/schemas/AppError'
        success:
          example: false
          type: boolean
      required:
        - success
        - error
      type: object
    AppError:
      description: Structured application error returned inside an `ErrorEnvelope`.
      properties:
        code:
          description: Machine-readable code, e.g. `SYMBOL_REQUIRED`, `EVENT_NOT_FOUND`.
          example: SYMBOL_REQUIRED
          type: string
        details:
          additionalProperties: true
          type: object
        message:
          description: >-
            Error detail as a string. Exact message content is not fixed and
            should not be hard-coded.
          example: string
          type: string
        operation:
          type: string
        request_id:
          type: string
        service:
          type: string
        type:
          description: >-
            Categorical error type. Use this for branching error-handling logic;
            the values are stable across endpoints:

            - `VALIDATION` — request body or query parameters failed validation.

            - `AUTHENTICATION` — missing, invalid, or expired token.

            - `AUTHORIZATION` — token is valid but lacks the required
            scope/permission.

            - `NOT_FOUND` — the requested resource does not exist.

            - `CONFLICT` — request conflicts with current state (e.g.
            duplicate).

            - `INTERNAL` — server-side error; retry or contact support.

            - `TIMEOUT` — operation took too long.

            - `UNKNOWN` — uncategorized error; check `message`.

            (Additional categorical values may appear in service-specific
            responses.)
          enum:
            - UNKNOWN
            - VALIDATION
            - AUTHENTICATION
            - AUTHORIZATION
            - NOT_FOUND
            - CONFLICT
            - INTERNAL
            - TIMEOUT
            - RATE_LIMIT
            - BAD_REQUEST
            - DATABASE
            - EXTERNAL_SERVICE
            - PRECONDITION_FAILED
            - SERVICE_UNAVAILABLE
            - GRPC
            - QUEUE
            - JSON_PARSING
          type: string
      required:
        - type
        - code
        - message
      type: object
  responses:
    PredMdBadGateway:
      content:
        application/json:
          example:
            error:
              code: UPSTREAM_UNAVAILABLE
              message: string
              type: EXTERNAL_SERVICE
            success: false
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
      description: >-
        Upstream data source failure. Response body is a prediction-market
        `ErrorEnvelope` with a structured `AppError`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.