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

# List all categories by city

> <Warning>We are soon moving to **v2 APIs** and **v1** will be deprecated. Switch to **v2** using the version selector above.</Warning>

Retrieve a list of all top-level experience categories (Tickets, Tours, Transportation, etc.) available in a specific city. Categories help organize products by experience type and are useful for building navigation menus or filtering product catalogs. Results are ordered by category rank.



## OpenAPI

````yaml GET /api/public/v1/category/list-by/city/
openapi: 3.1.0
info:
  title: Headout API Docs
  version: 0.0.1
servers:
  - url: https://www.headout.com
    description: Production server
  - url: https://www.sandbox-headout.com
    description: Sandbox server
security: []
paths:
  /api/public/v1/category/list-by/city/:
    get:
      tags:
        - Categories
      summary: List all categories by city
      description: >-
        <Warning>We are soon moving to **v2 APIs** and **v1** will be
        deprecated. Switch to **v2** using the version selector above.</Warning>


        Retrieve a list of all top-level experience categories (Tickets, Tours,
        Transportation, etc.) available in a specific city. Categories help
        organize products by experience type and are useful for building
        navigation menus or filtering product catalogs. Results are ordered by
        category rank.
      operationId: v1ListCategoriesByCity
      parameters:
        - name: cityCode
          in: query
          required: true
          schema:
            type: string
          description: City code to list categories for.
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: Number of items to skip before starting to collect the result set.
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
          description: Maximum number of items to return.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedCategories'
              example:
                items:
                  - id: 24
                    name: Broadway
                    cityCode: NEW_YORK
                    url: /category/24/broadway
                    image:
                      url: >-
                        https://cdn-imgix.headout.com/media/images/43b773a989e2563ab6c61758c8c69d5e-24-card.jpg
                    canonicalUrl: https://www.headout.com/category/24/broadway
                  - id: 121
                    name: Statue of Liberty
                    cityCode: NEW_YORK
                    url: /category/121/statue-of-liberty
                    image:
                      url: >-
                        https://cdn-imgix.headout.com/media/images/dee6f571a155af467e3ab3e1ebf680f1-121-new-york-statue-of-liberty-tickets-02.jpg
                    canonicalUrl: https://www.headout.com/category/121/statue-of-liberty
                nextUrl: >-
                  https://www.headout.com/api/public/v1/category/list-by/city?cityCode=NEW_YORK&offset=2&limit=2
                prevUrl: null
                total: 68
                nextOffset: 2
      security:
        - apiKeyAuth: []
      x-codeSamples:
        - lang: curl
          source: >
            curl --location
            'https://www.headout.com/api/public/v1/category/list-by/city/?cityCode=DUBAI'
            \

            --header 'Headout-Auth: <YOUR_API_KEY>'
components:
  schemas:
    PaginatedCategories:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Category'
          description: The categories in this page of results.
        nextUrl:
          type:
            - string
            - 'null'
          description: >-
            Full URL to fetch the next page of results. Null if on the last
            page.
        prevUrl:
          type:
            - string
            - 'null'
          description: >-
            Full URL to fetch the previous page of results. Null if on the first
            page.
        total:
          type: integer
          description: Total number of categories matching the query across all pages.
        nextOffset:
          type:
            - integer
            - 'null'
          description: >-
            Offset value to use in the next request to retrieve the following
            page.
    Category:
      type: object
      properties:
        id:
          type: integer
          description: >-
            Headout's identifier for this category. Used as a filter parameter
            in product listing endpoints.
        name:
          type: string
          description: Display name of the category (e.g., "Broadway", "City Tours").
        cityCode:
          type: string
          description: The city this category belongs to (e.g., `NEW_YORK`, `LONDON`).
        url:
          type: string
          description: >-
            Relative URL path for this category on Headout (e.g.,
            `/category/24/broadway`).
        image:
          type:
            - object
            - 'null'
          description: Representative image for this category.
          properties:
            url:
              type: string
              description: CDN URL of the category image.
        canonicalUrl:
          type:
            - string
            - 'null'
          description: >-
            The canonical Headout URL for this category page, suitable for
            linking and SEO.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Headout-Auth

````

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