BusinessMCP Read API

openapi: 3.2.0
info:
  title: BusinessMCP Read API
  version: 3.0.0
  description: 'The BI REST API: read your contacts, accounts and analytics sessions, send server-side events, export CSV, and drive the AI business analyst. Authenticate with a workspace key as `Authorization: Bearer mcph_...` (create one in Settings → API & access, or through the headless signup). Every key runs under its access policy; fields outside its data classes come back redacted. The same data and the full tool set are on the MCP endpoint.'
  contact:
    url: https://businessmcp.com/contact
servers:
- url: https://businessmcp.com/api/v1
security:
- bearer: []
tags:
- name: Read API
  description: Keyset-paginated reads of your CRM and analytics.
paths:
  /contacts:
    get:
      operationId: listContacts
      summary: List CRM contacts (keyset-paginated)
      description: 'Ordered by (updated_at, id). Revenue fields are null without the `revenue` data class and the company block is redacted without `enrichment`. With `segment`, pages that saved segment’s members. Rate limits: 600 requests/minute per key and 3000/minute per workspace (read bucket).


        Requires the `contact_pii` data class on the key’s access policy.'
      tags:
      - Read API
      parameters:
      - name: updated_since
        in: query
        description: ISO 8601 date (midnight UTC) or datetime; only rows updated at or after it.
        schema:
          type: string
      - name: cursor
        in: query
        description: Opaque keyset cursor from the previous page’s next_cursor.
        schema:
          type: string
      - name: limit
        in: query
        description: Page size (default 50, max 200).
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      - name: stage
        in: query
        description: Lifecycle stage, or `qualified`.
        schema:
          type: string
          enum:
          - visitor
          - lead
          - cold
          - mql
          - sql
          - customer
          - churned
          - qualified
      - name: account_id
        in: query
        description: Account id (uuid), not the external id.
        schema:
          type: string
          format: uuid
      - name: email
        in: query
        description: Exact email address.
        schema:
          type: string
      - name: segment
        in: query
        description: Saved segment id (uuid).
        schema:
          type: string
          format: uuid
      - name: include
        in: query
        description: '`identities` to list each contact’s visitor ids.'
        schema:
          type: string
          enum:
          - identities
      responses:
        '200':
          description: A page of contacts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      description: A contact record; fields outside the key’s data classes are redacted.
                  has_more:
                    type: boolean
                  next_cursor:
                    type:
                    - string
                    - 'null'
                  warning:
                    type: string
                required:
                - items
                - has_more
                - next_cursor
        '400':
          description: Invalid query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          description: Missing, invalid or revoked mcph_ key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '403':
          description: The key’s access policy does not include the required data class.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '404':
          description: Segment not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '429':
          description: Rate limited (empty body).
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait.
  /contacts/{id}:
    get:
      operationId: getContact
      summary: One contact with every identity listed
      description: 'The full record, visitor ids included. Rate limits: 600 requests/minute per key and 3000/minute per workspace (read bucket).


        Requires the `contact_pii` data class on the key’s access policy.'
      tags:
      - Read API
      parameters:
      - name: id
        in: path
        required: true
        description: Contact id (uuid).
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The contact record; fields outside the key’s data classes are redacted.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Missing, invalid or revoked mcph_ key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '403':
          description: The key’s access policy does not include the required data class.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '404':
          description: No such contact in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '429':
          description: Rate limited (empty body).
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait.
  /accounts:
    get:
      operationId: listAccounts
      summary: List accounts (companies your contacts belong to)
      description: 'Ordered by (updated_at, id). `mrr_usd` is null without the `revenue` data class. Rate limits: 600 requests/minute per key and 3000/minute per workspace (read bucket).


        Requires the `contact_pii` data class on the key’s access policy.'
      tags:
      - Read API
      parameters:
      - name: updated_since
        in: query
        description: ISO 8601 date (midnight UTC) or datetime; only rows updated at or after it.
        schema:
          type: string
      - name: cursor
        in: query
        description: Opaque keyset cursor from the previous page’s next_cursor.
        schema:
          type: string
      - name: limit
        in: query
        description: Page size (default 50, max 200).
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      - name: external_id
        in: query
        description: Your own account id, as sent to POST /group.
        schema:
          type: string
      - name: domain
        in: query
        description: Company domain.
        schema:
          type: string
      responses:
        '200':
          description: A page of accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      description: An account record.
                  has_more:
                    type: boolean
                  next_cursor:
                    type:
                    - string
                    - 'null'
                  warning:
                    type: string
                required:
                - items
                - has_more
                - next_cursor
        '400':
          description: Invalid query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          description: Missing, invalid or revoked mcph_ key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '403':
          description: The key’s access policy does not include the required data class.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '429':
          description: Rate limited (empty body).
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait.
  /events:
    get:
      operationId: listSessions
      summary: Analytics sessions, one row per session
      description: 'Keyset-paginated on (day, id) inside a window of at most 90 days (default: the last 30). `revenue_usd` is null without the `revenue` data class. Rate limits: 600 requests/minute per key and 3000/minute per workspace (read bucket).


        Requires the `behavior` data class on the key’s access policy.'
      tags:
      - Read API
      parameters:
      - name: from
        in: query
        description: First day, YYYY-MM-DD (inclusive).
        schema:
          type: string
          format: date
      - name: to
        in: query
        description: Last day, YYYY-MM-DD (inclusive; capped at today).
        schema:
          type: string
          format: date
      - name: updated_since
        in: query
        description: 'Alternative to `from`: a day or an instant, truncated to its day.'
        schema:
          type: string
      - name: visitor_id
        in: query
        description: One visitor’s sessions.
        schema:
          type: string
      - name: cursor
        in: query
        description: Opaque keyset cursor from the previous page’s next_cursor.
        schema:
          type: string
      - name: limit
        in: query
        description: Page size (default 50, max 200).
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      responses:
        '200':
          description: A page of sessions plus the window that was read.
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        description: 'A session: day, visitor, channel, entry/exit page, pageviews, duration, conversion, UTMs, geo and device.'
                    has_more:
                      type: boolean
                    next_cursor:
                      type:
                      - string
                      - 'null'
                    warning:
                      type: string
                  required:
                  - items
                  - has_more
                  - next_cursor
                - type: object
                  properties:
                    window:
                      type: object
                      properties:
                        from:
                          type: string
                        to:
                          type: string
        '400':
          description: Invalid query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          description: Missing, invalid or revoked mcph_ key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '402':
          description: Plan traffic limit exceeded; analytics reads are locked until upgrade.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '403':
          description: The key’s access policy does not include the required data class.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '429':
          description: Rate limited (empty body).
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait.
components:
  schemas:
    SimpleError:
      type: object
      properties:
        ok:
          const: false
        error:
          type: string
        detail:
          type: string
      required:
      - error
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: A BusinessMCP workspace key (mcph_…).
externalDocs:
  description: API reference
  url: https://businessmcp.com/docs/api