Unisson external-api API

openapi: 3.1.0
info:
  title: Unisson agent-evals external-api API
  version: 1.0.0
tags:
- name: external-api
paths:
  /api/v1/external/runs:
    post:
      tags:
      - external-api
      summary: Create External Run
      description: "Create a new run via External API.\n\nRequires scope: runs:create\n\nThe run will execute asynchronously. Use webhooks or polling to track status.\n\nReturns:\n    Run ID and initial status. Poll GET /external/runs/{id} or configure\n    webhooks to receive status updates."
      operationId: create_external_run_api_v1_external_runs_post
      parameters:
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalRunCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalRunResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/external/runs/{run_id}:
    get:
      tags:
      - external-api
      summary: Get External Run
      description: 'Get run status and results.


        Requires scope: runs:read


        Returns:

        - status: pending, queued, running, coordinating, authentication_required, waiting_for_input, completed, failed

        - If authentication_required: includes liveview_url for user login

        - If waiting_for_input: includes question for clarification

        - If completed: includes structured_output based on task_type

        - If failed: includes error_message'
      operationId: get_external_run_api_v1_external_runs__run_id__get
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalRunDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/external/runs/{run_id}/resume:
    post:
      tags:
      - external-api
      summary: Resume External Run
      description: 'Resume a run after user authentication or input.


        Call this after the user has completed authentication via liveview_url,

        or to provide an answer to a clarifying question.


        For authentication_required: Just call this endpoint (no body needed).

        For waiting_for_input: Include the answer in the request body.'
      operationId: resume_external_run_api_v1_external_runs__run_id__resume_post
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Run Id
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalRunResumeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalRunResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/external/status:
    get:
      tags:
      - external-api
      summary: External Status
      description: 'Validate API key and return basic status info.


        Use this endpoint to verify your API key is working correctly.'
      operationId: external_status_api_v1_external_status_get
      parameters:
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/external/webhook:
    put:
      tags:
      - external-api
      summary: Configure Webhook
      description: 'Configure webhook URL and events for the current API key.


        Allows integrators to self-service update their webhook configuration

        without going through the dashboard.'
      operationId: configure_webhook_api_v1_external_webhook_put
      parameters:
      - name: X-API-Key
        in: header
        required: true
        schema:
          type: string
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalWebhookConfigRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalWebhookConfigResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ExternalRunResumeRequest:
      properties:
        answer:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Answer
          description: Answer to clarifying question (if any)
      type: object
      title: ExternalRunResumeRequest
      description: Request to resume a paused run.
    ExternalWebhookConfigResponse:
      properties:
        webhook_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Webhook Url
        webhook_events:
          items:
            type: string
          type: array
          title: Webhook Events
        webhook_secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Webhook Secret
          description: Webhook signing secret. Only returned when a webhook URL is set for the first time.
      type: object
      required:
      - webhook_url
      - webhook_events
      title: ExternalWebhookConfigResponse
      description: Response after updating webhook configuration.
    ExternalStatusResponse:
      properties:
        status:
          type: string
          title: Status
        key_prefix:
          type: string
          title: Key Prefix
        scopes:
          items:
            type: string
          type: array
          title: Scopes
        is_sandbox:
          type: boolean
          title: Is Sandbox
        webhook_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Webhook Url
        webhook_events:
          items:
            type: string
          type: array
          title: Webhook Events
      type: object
      required:
      - status
      - key_prefix
      - scopes
      - is_sandbox
      - webhook_url
      - webhook_events
      title: ExternalStatusResponse
      description: Response for the status endpoint.
    ExternalRunResponse:
      properties:
        id:
          type: string
          format: uuid4
          title: Id
        status:
          type: string
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
        task_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Type
        external_reference_id:
          anyOf:
          - type: string
          - type: 'null'
          title: External Reference Id
        liveview_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Liveview Url
      type: object
      required:
      - id
      - status
      - created_at
      title: ExternalRunResponse
      description: Basic run response.
    ExternalRunCreateRequest:
      properties:
        task:
          anyOf:
          - type: string
            maxLength: 5000
            minLength: 1
          - type: 'null'
          title: Task
          description: Free-form task description. Mutually exclusive with task_type.
        task_type:
          anyOf:
          - type: string
            maxLength: 100
            minLength: 1
          - type: 'null'
          title: Task Type
          description: Predefined task type (e.g. 'carta_holdings'). Resolves to a curated prompt. Mutually exclusive with task.
        description:
          anyOf:
          - type: string
            maxLength: 120
            minLength: 1
          - type: 'null'
          title: Description
          description: Short cosmetic title for the run, shown in dashboard lists. Optional — defaults to the task text. Ignored when task_type is set (in that case the description is auto-set from the task_type's curated label, not the full resolved prompt).
        start_url:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Start Url
          description: Starting URL for browser session (defaults to org setting)
        external_reference_id:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: External Reference Id
          description: Your reference ID for tracking
        email:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Email
          description: Email of the user whose saved session to use. If the user exists in the organization, their browser session will be loaded/saved.
        user_hash:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: User Hash
          description: HMAC-SHA256(identity_secret, email) for identity verification. Required when the API key has an identity secret configured and email is provided.
        auth_token:
          anyOf:
          - type: string
            maxLength: 10000
          - type: 'null'
          title: Auth Token
          description: Auth token to inject into browser localStorage. Requires auth_injection to be configured on the API key. The token is encrypted at rest and only decrypted at point of use.
        client_ip:
          anyOf:
          - type: string
            maxLength: 45
          - type: 'null'
          title: Client Ip
          description: End-user IP address for residential proxy geolocation. When provided and proxy geolocation is enabled, the browser will appear to come from the same US state as this IP.
        sandbox_scenario:
          anyOf:
          - items:
              type: string
              enum:
              - common_stock
              - preferred_stock
              - options_iso
              - options_nso
              - warrants
              - convertible_note
              - unit
              - rsus
              - rsas
            type: array
          - type: string
            enum:
            - common_stock
            - preferred_stock
            - options_iso
            - options_nso
            - warrants
            - convertible_note
            - unit
            - rsus
            - rsas
            - all
          - type: 'null'
          title: Sandbox Scenario
          description: 'Sandbox only: which asset type(s) to return in the structured output. Accepts a single scenario string (e.g. ''common_stock'', ''all'') or a list of scenarios (e.g. [''common_stock'', ''preferred_stock'', ''options_iso'']). Ignored for live API keys. Defaults to ''all'' if not specified.'
        company_name:
          anyOf:
          - items:
              type: string
            type: array
          - type: string
          - type: 'null'
          title: Company Name
          description: 'Sandbox only: override the company name in sandbox holdings. Accepts a single name (applied to every holding) or a list of names — in which case each company is returned with the full set of selected scenarios (cross-product). Ignored for live API keys. Defaults to ''Sandbox Corp'' if not specified.'
        on_success_url:
          anyOf:
          - type: string
            maxLength: 2048
          - type: 'null'
          title: On Success Url
          description: URL the hosted auth page redirects to after the end-user signs in. Supports https:// and custom schemes (e.g. myapp://done). Optional — if absent, the page shows a generic 'logged in' screen the user closes manually.
        on_error_url:
          anyOf:
          - type: string
            maxLength: 2048
          - type: 'null'
          title: On Error Url
          description: URL the hosted auth page redirects to if authentication fails. Same scheme rules as on_success_url.
        sandbox_auth_outcome:
          anyOf:
          - type: string
            enum:
            - success
            - error
          - type: 'null'
          title: Sandbox Auth Outcome
          description: 'Sandbox only: force the auth-gating flow with a simulated outcome. The hosted page shows a 5-second ''signing in'' loader, then navigates to on_success_url / on_error_url and kicks off the simulated run exactly like the real flow. Ignored for live API keys.'
      type: object
      title: ExternalRunCreateRequest
      description: Request to create an external run.
    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
    ExternalWebhookConfigRequest:
      properties:
        webhook_url:
          type: string
          maxLength: 500
          title: Webhook Url
          description: URL to receive webhook events. Set to empty string to remove.
        webhook_events:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Webhook Events
          description: 'List of events to subscribe to. Valid events: run.authentication_required, run.input_required, run.completed, run.failed. If omitted on first-time setup, defaults to all events.'
      type: object
      required:
      - webhook_url
      title: ExternalWebhookConfigRequest
      description: Request to update webhook configuration via API key.
    ExternalRunDetailResponse:
      properties:
        id:
          type: string
          format: uuid4
          title: Id
        status:
          type: string
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
        task_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Type
        external_reference_id:
          anyOf:
          - type: string
          - type: 'null'
          title: External Reference Id
        liveview_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Liveview Url
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
        auth_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Auth Message
        question:
          anyOf:
          - type: string
          - type: 'null'
          title: Question
        response_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Response Text
        structured_output:
          anyOf:
          - additionalProperties: true
            type: object
          - items: {}
            type: array
          - type: 'null'
          title: Structured Output
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
      type: object
      required:
      - id
      - status
      - created_at
      title: ExternalRunDetailResponse
      description: Detailed run response with results.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer