openapi: 3.0.0
info:
  title: Thoughtly agent webhooks API
  version: 1.0.0
  description: 'The Thoughtly API lets you programmatically manage voice and chat AI agents,

    contacts, calls, webhooks, and automations. Voice Agents are referenced in

    the API as "interviews" for historical reasons. Authentication uses two

    headers: `x-api-token` and `team_id`, both available from the Developer

    Settings page of the Thoughtly dashboard.

    '
  contact:
    name: Thoughtly Support
    email: support@thoughtly.com
    url: https://thoughtly.com
  termsOfService: https://thoughtly.com/terms
  license:
    name: Proprietary
servers:
- url: https://api.thoughtly.com
  description: Production Server
security:
- ApiKeyAuth: []
  TeamIdAuth: []
tags:
- name: webhooks
  description: Webhook subscription, unsubscription, and automation triggers.
paths:
  /webhooks:
    get:
      summary: Get Currently Active Webhooks
      description: Retrieve all active webhook subscriptions for the authenticated workspace.
      operationId: getWebhooks
      tags:
      - webhooks
      responses:
        '200':
          description: List of webhook subscriptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /webhooks/subscribe:
    post:
      summary: Subscribe To Webhook
      description: Subscribe to a webhook event (e.g. NEW_RESPONSE, PHONE_TRANSFER).
      operationId: subscribeWebhook
      tags:
      - webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscribeRequest'
      responses:
        '200':
          description: Subscription created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /webhooks/unsubscribe:
    delete:
      summary: Unsubscribe From Webhook
      description: Remove a webhook subscription.
      operationId: unsubscribeWebhook
      tags:
      - webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookUnsubscribeRequest'
      responses:
        '200':
          description: Subscription removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
  /webhook/automation/{automation_id}:
    post:
      summary: Trigger Automation With Webhook
      description: Trigger an Automation that uses a Webhook trigger. Request body can be any arbitrary JSON; fields are available downstream in the automation steps.
      operationId: triggerAutomation
      tags:
      - webhooks
      parameters:
      - name: automation_id
        in: path
        required: true
        schema:
          type: string
        description: The ID of the Webhook-triggered automation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: Arbitrary JSON payload passed into the automation.
      security: []
      responses:
        '200':
          description: Automation triggered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
components:
  schemas:
    WebhookUnsubscribeRequest:
      type: object
      required:
      - type
      - url
      properties:
        type:
          type: string
          enum:
          - NEW_RESPONSE
          - PHONE_TRANSFER
          - FOLDER_NEW_RESPONSE
          - FOLDER_PHONE_TRANSFER
          - ACTION_FAILED
        data:
          type: string
        url:
          type: string
      additionalProperties: false
    GenericResponse:
      type: object
      required:
      - data
      properties:
        error:
          type: object
          nullable: true
          description: Populated only when the request fails.
        data:
          type: object
          additionalProperties: true
          description: Endpoint-specific payload.
    WebhookSubscribeRequest:
      type: object
      required:
      - type
      - url
      properties:
        type:
          type: string
          enum:
          - NEW_RESPONSE
          - PHONE_TRANSFER
        data:
          type: string
          nullable: true
        url:
          type: string
          format: uri
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-token
      description: API token from Thoughtly Developer Settings.
    TeamIdAuth:
      type: apiKey
      in: header
      name: team_id
      description: Team identifier from Thoughtly Developer Settings.