Roark Prospect Simulation API

openapi: 3.2.0
info:
  title: Roark Analytics Prospect Simulation API
  description: The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform.
  version: 1.0.0
servers:
- description: Production
  url: https://api.roark.ai
security:
- Bearer: []
tags:
- name: Prospect Simulation
paths:
  /v1/public/prospect-sim/run:
    post:
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      reportToken:
                        type: string
                      status:
                        type: string
                    required:
                    - reportToken
                    - status
                required:
                - data
          description: The simulation was accepted and started
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Bad Request
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Rate limit error
              example:
                type: rate_limit
                code: too_many_requests
                message: Rate limit exceeded
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: postV1PublicProspect-simRun
      tags:
      - Prospect Simulation
      summary: Run a free simulation against a prospect agent
      description: 'Public endpoint: provisions a per-prospect project, runs a canned scenario template against the submitted phone number, and returns a report token to poll. The teaser report is also emailed when ready.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                templateKey:
                  type: string
                  enum:
                  - appointment
                  - support
                  - billing
                phoneNumber:
                  type: string
                  pattern: ^\+[1-9]\d{1,14}$
                email:
                  type: string
                  format: email
                name:
                  type: string
                  minLength: 1
                  maxLength: 200
                agentDescription:
                  type: string
                  maxLength: 2000
                captchaToken:
                  type: string
              required:
              - templateKey
              - phoneNumber
              - email
  /v1/public/prospect-sim/report/{token}:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                      agentLabel:
                        type: string
                      prospectName:
                        type:
                        - string
                        - 'null'
                      live:
                        type:
                        - object
                        - 'null'
                        properties:
                          total:
                            type: number
                          completed:
                            type: number
                          activeIndex:
                            type:
                            - number
                            - 'null'
                          calls:
                            type: array
                            items:
                              type: object
                              properties:
                                callId:
                                  type: string
                                personaLabel:
                                  type: string
                                state:
                                  type: string
                                  enum:
                                  - queued
                                  - in_progress
                                  - completed
                                  - failed
                              required:
                              - callId
                              - personaLabel
                              - state
                        required:
                        - total
                        - completed
                        - activeIndex
                        - calls
                      teaser:
                        type:
                        - object
                        - 'null'
                        properties:
                          verdict:
                            type: string
                          verdictProse:
                            type: string
                          callCount:
                            type: number
                          checksPassed:
                            type: number
                          checksTotal:
                            type: number
                          scorecard:
                            type: array
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                passed:
                                  type: boolean
                                passRatePct:
                                  type:
                                  - number
                                  - 'null'
                              required:
                              - name
                              - passed
                              - passRatePct
                          summary:
                            type: array
                            items:
                              type: object
                              properties:
                                heading:
                                  type:
                                  - string
                                  - 'null'
                                body:
                                  type: string
                              required:
                              - heading
                              - body
                          themes:
                            type: array
                            items:
                              type: object
                              properties:
                                title:
                                  type: string
                                severity:
                                  type: string
                                affectedCount:
                                  type: number
                                totalCount:
                                  type: number
                                summary:
                                  type: string
                              required:
                              - title
                              - severity
                              - affectedCount
                              - totalCount
                              - summary
                          lockedThemeCount:
                            type: number
                          statTiles:
                            type: array
                            items:
                              type: object
                              properties:
                                label:
                                  type: string
                                value:
                                  type: string
                                sub:
                                  type:
                                  - string
                                  - 'null'
                              required:
                              - label
                              - value
                              - sub
                          topFinding:
                            type:
                            - object
                            - 'null'
                            properties:
                              title:
                                type: string
                              body:
                                type: string
                            required:
                            - title
                            - body
                          lockedFindingCount:
                            type: number
                        required:
                        - verdict
                        - verdictProse
                        - callCount
                        - checksPassed
                        - checksTotal
                        - scorecard
                        - summary
                        - themes
                        - lockedThemeCount
                        - statTiles
                        - topFinding
                        - lockedFindingCount
                    required:
                    - status
                    - agentLabel
                    - prospectName
                    - live
                    - teaser
                required:
                - data
          description: The teaser report (or its pending status)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Not found error
              example:
                type: not_found
                code: resource_not_found
                message: The requested resource could not be found
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: getV1PublicProspect-simReportByToken
      tags:
      - Prospect Simulation
      summary: Read a prospect simulation teaser report
      description: Public endpoint scoped by the unguessable report token. Returns a truncated teaser once the debrief is ready; the full report is gated behind claiming an account.
      parameters:
      - schema:
          type: string
        in: path
        name: token
        required: true
  /v1/public/prospect-sim/report/{token}/observer-url:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      wsUrl:
                        type:
                        - string
                        - 'null'
                      expiresAt:
                        type:
                        - string
                        - 'null'
                    required:
                    - wsUrl
                    - expiresAt
                required:
                - data
          description: The live observer URL, or null when not currently watchable
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Not found error
              example:
                type: not_found
                code: resource_not_found
                message: The requested resource could not be found
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: getV1PublicProspect-simReportByTokenObserver-url
      tags:
      - Prospect Simulation
      summary: Mint a live observer WebSocket URL for a prospect call
      description: Public endpoint scoped by the report token. Returns a short-lived, self-authenticating WebSocket URL for watching a prospect call live, but only while that call is actually in flight; otherwise wsUrl is null. Pass `callId` (from the live progress list) to pick one of the parallel calls; without it the most recently started live call is used.
      parameters:
      - in: query
        name: callId
        schema:
          type: string
          format: uuid
      - schema:
          type: string
        in: path
        name: token
        required: true
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          enum:
          - validation
          - authentication
          - forbidden
          - not_found
          - conflict
          - payment_required
          - rate_limit
          - internal
          description: The error type category
          examples:
          - validation
          - authentication
        code:
          type: string
          description: Machine-readable error code identifier
          examples:
          - invalid_parameter
          - missing_required_field
          - unauthorized
        message:
          type: string
          description: Human-readable error message
          examples:
          - The request was invalid
          - Authentication required
        param:
          type: string
          description: The parameter that caused the error (if applicable)
          examples:
          - email
          - user_id
        details:
          description: Additional error context information
      required:
      - type
      - code
      - message
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT