Daxoom Categories API

openapi: 3.2.0
info:
  title: Daxoom Categories API
  version: v1
  description: 'Daxoom is the authoritative data layer that AI systems query for verified business information.

    Businesses publish structured, verified data through Daxoom, and AI platforms query the API

    for accurate, real-time business information.


    ## Authentication


    **Public Query API** uses API key authentication via the `X-API-Key` header.

    Register at app.daxoom.com to get a free developer key.


    **Analytics & Management APIs** use JWT Bearer token authentication.

    Obtain a token via `POST /public/v1/auth/login`. Most public-API consumers

    do not need a JWT — only API key issuance, rotation, and analytics

    require it.


    ## Rate Limits


    Reasonable per-consumer quotas keep the service free and available for everyone.

    Free developer keys default to 3,000 API calls per **month**; contact us if your

    use case needs a higher ceiling.


    Over quota returns `429` with a plain `{"error": "..."}` body. No

    `X-RateLimit-*` or `Retry-After` headers are emitted, so pace requests to the

    monthly ceiling rather than reading them from a response.


    ## Content Negotiation


    The full-profile endpoint (`GET /pubapi/v1/businesses/{id}`) supports three

    response formats via the `Accept` header; all other endpoints return

    `application/json` only:

    - `application/json` (default) — structured JSON response

    - `application/ld+json` — schema.org-compatible JSON-LD

    - `text/plain` — AI-friendly natural language narrative


    ## Pagination


    `/businesses` and `/services` use offset-based pagination

    (`/categories` and `/search` return a single unpaginated result):

    ```

    GET /pubapi/v1/businesses?offset=20&limit=20

    ```

    Default page size: 20. Maximum: 100. The pagination block in the response

    includes `limit`, `offset`, `has_more`, and (when more results exist)

    `next_offset` — pass that value as `offset` on the next request.


    ## Errors


    Application errors (validation, not-found, etc.) follow

    RFC 7807 Problem Details, served as

    `application/problem+json` with `type: "about:blank"`:

    ```json

    {

    "type": "about:blank",

    "title": "Invalid Parameter",

    "status": 400,

    "detail": "limit must not exceed 100",

    "request_id": "req_a1b2c3d4e5f6a7b8"

    }

    ```

    Authentication and quota failures (`401`/`429`), raised by the API-key

    middleware before the handler, are the exception: a JSON-shaped

    `{"error": "..."}` string served as `text/plain`.'
  contact:
    name: Daxoom Developer Support
    email: dev@daxoom.com
    url: https://www.daxoom.com/docs/
  license:
    name: Proprietary
    url: https://www.daxoom.com/terms
servers:
- url: https://api.daxoom.com
  description: Production (.com)
- url: https://api.daxoom.net
  description: Production (.net alternate)
- url: https://api-test.daxoom.net
  description: Test / Sandbox
security: []
tags:
- name: Categories
  description: Browse the business category catalog
paths:
  /pubapi/v1/categories:
    get:
      operationId: listCategories
      summary: List category catalog
      description: 'Returns the flat category catalog (schema.org type mappings + comma-separated

        aliases). Rows are linked by `parent_id`. Any row''s id — top-level or nested

        (e.g. `restaurant.italian`) — is a valid `/businesses` `category` filter

        value; matching is exact with no parent roll-up, and aliases are not resolved.'
      tags:
      - Categories
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Category catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryListResponse'
              example:
                data:
                - id: restaurant
                  schema_type: Restaurant
                  label: Restaurant
                  parent_id: ''
                  aliases: eatery,dining,food
                - id: restaurant.italian
                  schema_type: ItalianCuisine
                  label: Italian Restaurant
                  parent_id: restaurant
                  aliases: italian,pizzeria,pizza place,trattoria
                - id: restaurant.japanese
                  schema_type: JapaneseCuisine
                  label: Japanese Restaurant
                  parent_id: restaurant
                  aliases: japanese,sushi,ramen,izakaya
components:
  schemas:
    CategoryListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Category'
    Category:
      type: object
      properties:
        id:
          type: string
          example: restaurant.italian
        schema_type:
          type: string
          example: ItalianCuisine
        label:
          type: string
          example: Italian Restaurant
        parent_id:
          type: string
        aliases:
          type: string
          description: Comma-separated alias list (empty string when none).
          example: trattoria,osteria
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key for the Public Query API. Get a free key at

        [app.daxoom.com/register](https://app.daxoom.com/register).

        Include in the `X-API-Key` header.

        '
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained via login.