Daxoom Search API

openapi: 3.2.0
info:
  title: Daxoom Search 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: Search
  description: Semantic and natural language search
paths:
  /pubapi/v1/search:
    get:
      operationId: semanticSearch
      summary: Semantic search
      description: 'Natural language search resolved to structured filters.

        Pass a free-text query and get matching businesses.


        Example: `?q=italian restaurant with outdoor seating near Irvine`'
      tags:
      - Search
      security:
      - ApiKeyAuth: []
      parameters:
      - name: q
        in: query
        required: true
        description: Natural language search query
        schema:
          type: string
        example: italian restaurant with outdoor seating near Irvine
      - name: city
        in: query
        description: Optional city filter applied alongside the query.
        schema:
          type: string
        example: Irvine
      responses:
        '200':
          description: 'Top matches. This endpoint is not paginated — no `pagination` block is

            returned and `offset`/`limit` are not read. Use `/businesses` for

            paginated filtering.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BusinessSummary'
                  meta:
                    $ref: '#/components/schemas/Meta'
  /pubapi/v1/services:
    get:
      operationId: searchServices
      summary: Search services / menu items / products
      description: 'Cross-business search over individual offering items (services, menu items,

        products) with geo, category, type, and price filters — the REST twin of the

        `search_services` MCP tool. Paginated via `limit`/`offset`.'
      tags:
      - Search
      security:
      - ApiKeyAuth: []
      parameters:
      - name: q
        in: query
        description: Free-text query over item name, item description, or offering name.
        schema:
          type: string
      - name: category
        in: query
        schema:
          type: string
      - name: type
        in: query
        description: 'Offering type: `S` service, `M` menu section, `P` product, `K` package.'
        schema:
          type: string
          enum:
          - S
          - M
          - P
          - K
      - name: min_price
        in: query
        schema:
          type: number
      - name: max_price
        in: query
        schema:
          type: number
      - name: lat
        in: query
        schema:
          type: number
      - name: lng
        in: query
        schema:
          type: number
      - name: radius
        in: query
        description: Radius in metres around lat/lng (0 = no geo filter).
        schema:
          type: number
      - name: sort
        in: query
        description: 'Ordering: `price`, `distance`, or `relevance` (default).'
        schema:
          type: string
          enum:
          - price
          - distance
          - relevance
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Matched services (one page)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      description: A matched offering item with its business, location, and price.
                  pagination:
                    $ref: '#/components/schemas/Pagination'
components:
  schemas:
    Confidence:
      type: object
      description: Composite confidence signals.
      properties:
        score:
          type: number
        verification_level:
          type: string
        freshness:
          type: string
        completeness:
          type: number
        age_days:
          type:
          - integer
          - 'null'
    BusinessSummary:
      type: object
      description: Abbreviated business profile for list results.
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        category_id:
          type: string
          description: Source category slug (e.g. `italian_restaurant`). NOT a `/categories` id — the `category` filter takes `/categories` (group) ids, not this value.
          example: italian_restaurant
        category:
          type: string
          description: Human-readable category label.
          example: Italian Restaurant
        verification_level:
          type: string
          enum:
          - owner_verified
          - enriched_unverified
          - seed_data
          - claimed
        completeness_score:
          type: number
          description: Data completeness score (0.0–1.0).
        version:
          type: integer
        status:
          type: string
          description: Business status code (`A` active).
        confidence:
          $ref: '#/components/schemas/Confidence'
        city:
          type: string
        region:
          type: string
        country:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        updated_at:
          type: string
          format: date-time
    Pagination:
      type: object
      properties:
        limit:
          type: integer
          description: Page size used for this response.
        offset:
          type: integer
          description: Offset used for this response.
        total:
          type: integer
          description: Running count of items seen through this page (`offset` + rows on this page) — not the page size and not the full result-set size.
        has_more:
          type: boolean
          description: True when at least one more page exists.
        next_offset:
          type: integer
          description: Offset to use for the next request. Present only when `has_more` is true.
    Meta:
      type: object
      properties:
        request_id:
          type: string
        timestamp:
          type: string
          format: date-time
        version:
          type: string
  parameters:
    offset:
      name: offset
      in: query
      description: Pagination offset — number of rows to skip. Use the `next_offset` from the previous response to advance.
      schema:
        type: integer
        minimum: 0
        default: 0
    limit:
      name: limit
      in: query
      description: Page size (default 20, max 100)
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  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.