Daxoom API Keys API

openapi: 3.2.0
info:
  title: Daxoom API Keys 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: API Keys
  description: Manage your API keys
paths:
  /api/v1/api_key/generate:
    post:
      operationId: generateApiKey
      summary: Generate an API key
      description: 'Mints a new API key owned by your account. The full key is returned only

        once in the response — store it securely. Subsequent lists show only the

        prefix.'
      tags:
      - API Keys
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - key_name
              properties:
                key_name:
                  type: string
                  description: Human-readable name for this key
                  example: My AI Agent - Production
                scopes:
                  type: string
                  description: 'Space-delimited scopes (default: query). Grant ''write'' to allow the feedback MCP tools (submit_review, report_incorrect_data).'
                  example: query
      responses:
        '201':
          description: API key created (wrapped in the standard `{data, meta}` envelope).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      api_key:
                        type: string
                        description: Full API key — shown only once.
                      key_prefix:
                        type: string
                        description: First 8 characters (for identification).
                  meta:
                    $ref: '#/components/schemas/Meta'
              example:
                data:
                  api_key: dxm_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
                  key_prefix: dxm_a1b2
  /api/v1/api_key/roll:
    post:
      operationId: rollApiKey
      summary: Roll (rotate) an API key
      description: 'Issues a replacement key for the given key id; the old key keeps working

        for a 24-hour grace period, then stops.'
      tags:
      - API Keys
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: integer
                  description: The api_key id to roll.
      responses:
        '200':
          description: Replacement key issued (wrapped in the standard `{data, meta}` envelope).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      api_key:
                        type: string
                        description: New API key — shown only once.
                      key_prefix:
                        type: string
                  meta:
                    $ref: '#/components/schemas/Meta'
  /api/v1/api_key/list:
    get:
      operationId: listApiKeys
      summary: List API keys
      description: 'Returns your account''s API keys via the generic REST list action (GET).

        Key values are masked — only the prefix is shown. Supports `?limit=` and

        `?offset=` query paging.'
      tags:
      - API Keys
      security:
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: List of API keys (generic-REST paged object under `data`).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/ApiKeyInfo'
                      limit:
                        type: integer
                      offset:
                        type: integer
                      total:
                        type: integer
                  meta:
                    $ref: '#/components/schemas/Meta'
  /api/v1/api_key/delete:
    delete:
      operationId: revokeApiKey
      summary: Revoke an API key
      description: 'Revokes the API key via the generic REST delete action (DELETE; POST is also

        accepted). Pass the key id as a query filter, e.g. `?id=42`. Requests using

        the revoked key return 401.'
      tags:
      - API Keys
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: query
        required: true
        description: The api_key id to revoke.
        schema:
          type: integer
      responses:
        '200':
          description: Key revoked; a confirmation message is returned under the standard data/meta envelope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                  meta:
                    $ref: '#/components/schemas/Meta'
components:
  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
  schemas:
    ApiKeyInfo:
      type: object
      properties:
        id:
          type: integer
        key_name:
          type: string
        key_prefix:
          type: string
        scopes:
          type: string
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        last_used_at:
          type: string
          format: date-time
    Meta:
      type: object
      properties:
        request_id:
          type: string
        timestamp:
          type: string
          format: date-time
        version:
          type: string
  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.