Daxoom System API

openapi: 3.2.0
info:
  title: Daxoom System 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: System
  description: Health checks and status
paths:
  /health:
    servers:
    - url: https://api.daxoom.com
      description: Production (.com) — note the health endpoint is mounted at the root, not under /v1.
    - url: https://api.daxoom.net
      description: Production (.net alternate)
    - url: https://api-test.daxoom.net
      description: Test / Sandbox
    get:
      operationId: healthCheck
      summary: Health check
      description: 'Public health check endpoint. No authentication required. Mounted at the

        host root (not under `/v1`) so VPC-internal probes can hit it without

        version-coupling.'
      tags:
      - System
      security: []
      responses:
        '200':
          description: Service is healthy (plain-text liveness).
          content:
            text/plain:
              schema:
                type: string
                example: ok
  /public/v1/auth/login:
    post:
      operationId: authLogin
      summary: Obtain a JWT bearer token
      description: 'Exchange username + password for a JWT bearer token. The token is required

        as `Authorization: Bearer …` for the Analytics and API-Key Management

        endpoints. Most public-API consumers do not need this — they authenticate

        with an `X-API-Key` header on the Public Query API.'
      tags:
      - System
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - username
              - password
              properties:
                username:
                  type: string
                password:
                  type: string
                  format: password
      responses:
        '200':
          description: 'Authenticated (standard `{data, meta}` envelope). Two shapes: full login

            returns `{token, userId, partnerId, menu, twoFactorRequired: false}`;

            when 2FA is pending, `data` is only `{twoFactorRequired: true, loginToken}`

            — exchange `loginToken` via the 2FA verify endpoint for the real token.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      token:
                        type: string
                        description: JWT bearer token (absent while 2FA is pending).
                      userId:
                        type: integer
                      partnerId:
                        type: integer
                      menu:
                        type: array
                        items:
                          type: object
                        description: Role-scoped UI menu (opaque to API clients).
                      twoFactorRequired:
                        type: boolean
                      loginToken:
                        type: string
                        description: Short-lived 2FA handoff token; present only when `twoFactorRequired` is true.
                  meta:
                    $ref: '#/components/schemas/Meta'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Meta:
      type: object
      properties:
        request_id:
          type: string
        timestamp:
          type: string
          format: date-time
        version:
          type: string
  responses:
    Unauthorized:
      description: 'Missing or invalid authentication. Raised by the API-key middleware via

        `http.Error`, so the body is a JSON-shaped string delivered as

        `text/plain; charset=utf-8` — not RFC 7807, not `application/json`.

        '
      content:
        text/plain:
          schema:
            type: string
          example: '{"error":"invalid API key"}'
  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.