generated: '2026-08-13'
method: searched
source: https://api.knownwell.com/docs
derived_from: openapi/2x-knownwell-openapi.json
note: >-
  Cross-cutting request/response semantics for the Knownwell commercial-intelligence API,
  the machine-readable surface 2X acquired in June 2026. The spec is FastAPI-generated,
  which sets several of these conventions (the 422 validation envelope, the auto-generated
  operationIds) rather than a hand-authored design system.
authentication:
  style: api-key-header
  header: X-API-Key
  detail: authentication/2x-authentication.yml
idempotency:
  supported: false
  note: >-
    No idempotency key is documented and none appears in the OpenAPI. This is a low-risk
    absence rather than a gap — 24 of the 27 operations are GET and therefore naturally
    idempotent. The three non-GET operations are API-key administration (POST create,
    DELETE revoke), where a retried create would mint a duplicate key with no way to
    deduplicate it. No Idempotency pointer is emitted for this provider.
pagination:
  style: limit-offset
  params:
  - name: limit
    default: 100
    max: 500
    note: max is 500 on list endpoints per the docs
  - name: offset
    default: 0
  response_fields:
  - total
  - clients
  - streams
  - portfolios
  note: >-
    List responses wrap the collection alongside a `total` count and the owning `customerId`
    (see ClientListResponse, StreamListResponse, PortfolioListResponse). There is no cursor,
    no next-page link, and no Link header — a client paginates by incrementing offset until
    it has consumed `total`.
filtering:
  common_params:
  - name: include_archived
    note: present on nearly every client-scoped read; archived clients are excluded by default
  - name: include_inactive
    note: stream reads
  - name: include_system
    note: portfolio reads, to include system-managed portfolios
  - name: week
    note: alignment reads are addressed by week
  - name: months
    note: client history window
  search:
    operation: search_clients_v1_clients_search_get
    params: [query, fields]
field_expansion:
  supported: false
  note: no expand/fields sparse-fieldset mechanism beyond the `fields` param on client search
metadata:
  supported: true
  note: >-
    Clients carry a structured `metadata` object (accountOwner, annualRevenue, industry,
    location, accountStatus, domain, clientType, revenueTTM, revenueF12M) plus a free-form
    `extraColumns` map for customer-defined columns.
request_tracing:
  header: null
  note: >-
    No request-id header is documented, and none was observed on the 401 responses probed on
    2026-08-13. The MCP host returns a Google Cloud x-cloud-trace-context header, but that is
    infrastructure, not a published contract.
versioning:
  scheme: uri-path
  current: v1
  detail: lifecycle/2x-lifecycle.yml
error_envelope:
  format: custom-json
  fields: [error, detail, status_code]
  validation_variant:
    status: 422
    schema: HTTPValidationError
    shape: '{"detail":[{"loc":[...],"msg":"...","type":"..."}]}'
    note: FastAPI's standard validation envelope; differs from the flat error shape above
  rfc9457: false
  detail: errors/2x-problem-types.yml
rate_limit_signaling:
  headers: [X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset]
  exhaustion_status: 429
  detail: rate-limits/2x-rate-limits.yml
content_types:
  request: none
  response:
  - application/json
  - text/csv
  note: >-
    text/csv only on export_clients_csv_v1_clients_export_csv_get; every other operation
    returns JSON. No request bodies except API-key creation.
naming:
  path_case: kebab-case
  field_case: camelCase
  note: >-
    Response fields are camelCase (clientId, knownwellScore, lastContactDate) while query
    parameters are snake_case (include_archived, risk_level, status_filter) — an internal
    inconsistency worth knowing before writing a client.
  operation_ids:
    style: fastapi-autogenerated
    example: get_client_alignment_v1_clients__client_id__alignment_get
    note: >-
      operationIds are FastAPI's auto-generated method+path mangling rather than curated
      names, so they are stable but verbose and leak the path into the identifier.
mutability:
  read_only: true
  note: >-
    Every data operation is a GET. The only writes in the contract create or revoke API
    keys. An agent cannot change commercial-intelligence state through this API.