Peerbound Moments API

openapi: 3.2.0
info:
  title: Peerbound Public Moments API
  description: 'The Peerbound Public API provides read-only access to your organization''s data for integration

    with external systems such as data warehouses and business intelligence tools.


    ## Authentication


    All requests require an API key passed via the `X-API-Key` header.


    **To obtain an API key:**

    1. Navigate to Settings > API Keys in the Peerbound web app

    2. Generate a new key

    3. Copy the key immediately—it will only be shown once


    **Note:** Only organization admins can access the API Keys settings page. API access is not

    enabled by default and must be enabled by the Peerbound team for your organization.


    ## Incremental Sync


    This API is designed for executing incremental data syncs. All list endpoints:

    - Return results ordered by `updated_at` ascending (oldest updates first)

    - Support an `updated_since` filter to fetch only records modified after a given timestamp

    - Use cursor-based pagination for efficient iteration through large datasets

    - Include deleted records (with `is_deleted: true`) so you can sync deletions


    **Recommended sync pattern:**

    1. On first sync, fetch all records without `updated_since`

    2. Store the `updated_at` timestamp of the most recent record

    3. On subsequent syncs, pass that timestamp as `updated_since` to fetch only changes


    *Warning:* If a record is updated while you are paginating through results, the same record may appear

    again in a later page. Your sync logic should handle this by prioritizing the version of the

    record returned in the later page.


    ## Rate Limiting


    To protect infrastructure and ensure fair usage, the API enforces rate limits:


    - **1,000 requests per hour** (hourly limit)

    - **5 requests per second** (burst limit)


    Rate limits are applied **per organization**, not per API key. Multiple API keys for the same

    organization share the same limit.


    The hourly limit uses a fixed window that resets at the top of each hour (e.g., 10:00, 11:00).

    When you exceed the limit, you''ll receive a `429 Too Many Requests` response with a `Retry-After`

    header indicating how long to wait.


    All responses include rate limit headers:


    | Header | Description |

    |--------|-------------|

    | `RateLimit-Limit` | Maximum requests allowed per hour |

    | `RateLimit-Remaining` | Requests remaining in the current window |

    | `RateLimit-Reset` | Seconds until the rate limit resets |


    ## Support


    If you encounter unexpected issues, please contact **support@peerbound.com**. To help us

    investigate, include:


    - The request payload that caused the issue

    - The `X-Request-ID` header value from the response


    Every API response includes an `X-Request-ID` header with a unique identifier for that request.'
  version: v1
servers:
- url: /api/public/v1
tags:
- name: Moments
paths:
  /moments:
    get:
      tags:
      - Moments
      summary: List moments
      description: Retrieve a paginated list of moments (quotes) for your organization.
      operationId: list_moments_moments_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          description: Maximum number of moments to return
          default: 100
          title: Limit
        description: Maximum number of moments to return
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor from previous response
          title: Cursor
        description: Pagination cursor from previous response
      - name: updated_since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Filter records updated at or after this timestamp (ISO 8601)
          title: Updated Since
        description: Filter records updated at or after this timestamp (ISO 8601)
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse_Moment_'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: API access not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /moments/{moment_id}:
    get:
      tags:
      - Moments
      summary: Get a moment
      description: Retrieve a single moment (quote) by its ID.
      operationId: get_moment_moments__moment_id__get
      parameters:
      - name: moment_id
        in: path
        required: true
        schema:
          type: string
          title: Moment Id
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Moment'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: API access not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Moment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Moment:
      properties:
        id:
          type: string
          title: Id
          description: Unique Peerbound identifier for the quote
        text:
          type: string
          title: Text
          description: The quote text
        approval_state:
          type: string
          enum:
          - Not Approved
          - Approved – Anonymous
          - Approved – Public
          title: Approval State
          description: Approval status of the quote
        moment_type:
          anyOf:
          - type: string
            enum:
            - AI Hype
            - Competitive Clue
            - Expansion Potential
            - Impact Insight
            - Partner Love
            - People Praise
            - Sentiment Signal
            - Use Case Finder
          - type: 'null'
          title: Moment Type
          description: Category/type of the moment
        recording:
          anyOf:
          - $ref: '#/components/schemas/RecordingSource'
          - type: 'null'
          description: Source recording metadata (null for external moments)
        account:
          anyOf:
          - $ref: '#/components/schemas/LinkedAccount'
          - type: 'null'
          description: Associated account (customer)
        contact:
          anyOf:
          - $ref: '#/components/schemas/LinkedContact'
          - type: 'null'
          description: Associated contact (person)
        occurred_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Occurred At
          description: When the moment occurred (ISO 8601)
        is_deleted:
          type: boolean
          title: Is Deleted
          description: Whether the moment quote has been deleted
        created_at:
          type: string
          title: Created At
          description: Timestamp when the quote was created (ISO 8601)
        updated_at:
          type: string
          title: Updated At
          description: Timestamp when the quote or moment was last updated (ISO 8601)
      type: object
      required:
      - id
      - text
      - approval_state
      - is_deleted
      - created_at
      - updated_at
      title: Moment
      description: 'A customer moment (quote) extracted from a call recording.


        Moments are flattened from the internal moment/moment_quote structure

        to expose quotes directly at the top level.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PaginationInfo:
      properties:
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
          description: Opaque cursor to fetch the next page. Null if no more results.
        has_more:
          type: boolean
          title: Has More
          description: Whether there are more results available
        limit:
          type: integer
          title: Limit
          description: Maximum number of results requested
      type: object
      required:
      - has_more
      - limit
      title: PaginationInfo
      description: 'Pagination metadata for list responses.


        All list endpoints use cursor-based pagination with consistent metadata.'
    RecordingSource:
      properties:
        type:
          anyOf:
          - type: string
            enum:
            - attention
            - avoma
            - bluedot
            - chorus
            - clari
            - fireflies
            - gong
            - goodmeetings
            - granola
            - momentum
            - outreach
            - salesloft
          - type: string
            const: ai_interview
          title: Type
          description: Recording platform identifier
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
          description: Call ID on the source platform
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
          description: Title of the recording/call
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
          description: Link to the recording on source platform
      type: object
      required:
      - type
      title: RecordingSource
      description: Source recording metadata for a moment.
    ListResponse_Moment_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Moment'
          type: array
          title: Data
          description: List of resources
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
          description: Pagination information
      type: object
      required:
      - data
      - pagination
      title: ListResponse[Moment]
    LinkedAccount:
      properties:
        id:
          type: string
          title: Id
          description: Unique Peerbound identifier for the account
        name:
          type: string
          title: Name
          description: Name of the account
        salesforce_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Salesforce Id
          description: Salesforce Account ID if synced
        hubspot_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Hubspot Id
          description: HubSpot Company ID if synced
      type: object
      required:
      - id
      - name
      title: LinkedAccount
      description: 'Account (customer company) linked to a resource.


        Used for stories, reviews, and moments to reference the associated account.'
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
          description: Error details
      type: object
      required:
      - error
      title: ErrorResponse
      description: Standard error response format for all API errors.
    ErrorDetail:
      properties:
        code:
          type: string
          title: Code
          description: Machine-readable error code
        message:
          type: string
          title: Message
          description: Human-readable error message
      type: object
      required:
      - code
      - message
      title: ErrorDetail
      description: Details of an API error.
    LinkedContact:
      properties:
        id:
          type: string
          title: Id
          description: Unique Peerbound identifier for the contact
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Full name of the contact
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
          description: Email address of the contact
        salesforce_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Salesforce Id
          description: Salesforce Contact ID if synced
        hubspot_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Hubspot Id
          description: HubSpot Contact ID if synced
      type: object
      required:
      - id
      title: LinkedContact
      description: 'Contact (person) linked to a resource.


        Used for reviews and moments to reference the associated contact.'