openapi: 3.1.0
info:
  title: Exa Agent Webhooks API
  version: 2.0.0
  description: Exa Agent API - subset of the Exa Public API.
servers:
- url: https://api.exa.ai
security:
- apiKey: []
- bearer: []
tags:
- name: Webhooks
paths:
  /v0/webhooks:
    servers:
    - url: https://api.exa.ai/websets
    post:
      operationId: webhooks-create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookParameters'
      responses:
        '200':
          description: Webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
      summary: Create a Webhook
      tags:
      - Webhooks
      security:
      - apiKey: []
      - bearer: []
      x-codeSamples:
      - lang: javascript
        label: JavaScript
        source: "// npm install exa-js\nimport Exa from \"exa-js\";\nconst exa = new Exa(\"YOUR_EXA_API_KEY\");\n\nconst webhook = await exa.websets.webhooks.create({\n  url: \"https://api.yourapp.com/webhooks/exa\",\n  events: [\"webset.completed\", \"enrichment.completed\"],\n});\n\nconsole.log(`Created webhook: ${webhook.id}`);"
      - lang: python
        label: Python
        source: "# pip install exa-py\nfrom exa_py import Exa\n\nexa = Exa(\"YOUR_EXA_API_KEY\")\n\nwebhook = exa.websets.webhooks.create(\n    params={\n        \"url\": \"https://api.yourapp.com/webhooks/exa\",\n        \"events\": [\"webset.completed\", \"enrichment.completed\"],\n    }\n)\n\nprint(f\"Created webhook: {webhook.id}\")"
    get:
      operationId: webhooks-list
      parameters:
      - name: cursor
        required: false
        in: query
        description: The cursor to paginate through the results
        schema:
          minLength: 1
          type: string
      - name: limit
        required: false
        in: query
        description: The number of results to return
        schema:
          minimum: 1
          maximum: 200
          default: 25
          type: number
      responses:
        '200':
          description: List of webhooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWebhooksResponse'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
      summary: List webhooks
      tags:
      - Webhooks
      security:
      - apiKey: []
      - bearer: []
      x-codeSamples:
      - lang: javascript
        label: JavaScript
        source: "// npm install exa-js\nimport Exa from \"exa-js\";\nconst exa = new Exa(\"YOUR_EXA_API_KEY\");\n\nconst webhooks = await exa.websets.webhooks.list();\n\nconsole.log(`Found ${webhooks.data.length} webhooks`);\nwebhooks.data.forEach((webhook) => {\n  console.log(`- ${webhook.id}: ${webhook.url}`);\n});"
      - lang: python
        label: Python
        source: "# pip install exa-py\nfrom exa_py import Exa\n\nexa = Exa(\"YOUR_EXA_API_KEY\")\n\nwebhooks = exa.websets.webhooks.list()\n\nprint(f\"Found {len(webhooks.data)} webhooks\")\nfor webhook in webhooks.data:\n    print(f\"- {webhook.id}: {webhook.url}\")"
  /v0/webhooks/{id}:
    servers:
    - url: https://api.exa.ai/websets
    get:
      operationId: webhooks-get
      parameters:
      - name: id
        required: true
        in: path
        description: The id of the webhook
        schema:
          type: string
      responses:
        '200':
          description: Webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
        '404':
          description: Webhook not found
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
      summary: Get a Webhook
      tags:
      - Webhooks
      security:
      - apiKey: []
      - bearer: []
      x-codeSamples:
      - lang: javascript
        label: JavaScript
        source: '// npm install exa-js

          import Exa from "exa-js";

          const exa = new Exa("YOUR_EXA_API_KEY");


          const webhook = await exa.websets.webhooks.get("webhook_id");


          console.log(`Webhook: ${webhook.id} - ${webhook.url}`);'
      - lang: python
        label: Python
        source: '# pip install exa-py

          from exa_py import Exa


          exa = Exa("YOUR_EXA_API_KEY")


          webhook = exa.websets.webhooks.get("webhook_id")


          print(f"Webhook: {webhook.id} - {webhook.url}")'
    patch:
      operationId: webhooks-update
      parameters:
      - name: id
        required: true
        in: path
        description: The id of the webhook
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookParameters'
      responses:
        '200':
          description: Webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
        '404':
          description: Webhook not found
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
      summary: Update a Webhook
      tags:
      - Webhooks
      security:
      - apiKey: []
      - bearer: []
      x-codeSamples:
      - lang: javascript
        label: JavaScript
        source: "// npm install exa-js\nimport Exa from \"exa-js\";\nconst exa = new Exa(\"YOUR_EXA_API_KEY\");\n\nconst webhook = await exa.websets.webhooks.update(\"webhook_id\", {\n  url: \"https://api.yourapp.com/webhooks/exa-updated\",\n  events: [\"webset.completed\"],\n});\n\nconsole.log(`Updated webhook: ${webhook.id}`);"
      - lang: python
        label: Python
        source: "# pip install exa-py\nfrom exa_py import Exa\n\nexa = Exa(\"YOUR_EXA_API_KEY\")\n\nwebhook = exa.websets.webhooks.update(\n    \"webhook_id\",\n    params={\n        \"url\": \"https://api.yourapp.com/webhooks/exa-updated\",\n        \"events\": [\"webset.completed\"],\n    },\n)\n\nprint(f\"Updated webhook: {webhook.id}\")"
    delete:
      operationId: webhooks-delete
      parameters:
      - name: id
        required: true
        in: path
        description: The id of the webhook
        schema:
          type: string
      responses:
        '200':
          description: Webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
        '404':
          description: Webhook not found
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
      summary: Delete a Webhook
      tags:
      - Webhooks
      security:
      - apiKey: []
      - bearer: []
      x-codeSamples:
      - lang: javascript
        label: JavaScript
        source: '// npm install exa-js

          import Exa from "exa-js";

          const exa = new Exa("YOUR_EXA_API_KEY");


          await exa.websets.webhooks.delete("webhook_id");


          console.log("Webhook deleted successfully");'
      - lang: python
        label: Python
        source: '# pip install exa-py

          from exa_py import Exa


          exa = Exa("YOUR_EXA_API_KEY")


          exa.websets.webhooks.delete("webhook_id")


          print("Webhook deleted successfully")'
components:
  schemas:
    Webhook:
      type:
      - object
      properties:
        id:
          type:
          - string
          description: The unique identifier for the webhook
        object:
          type: string
          const: webhook
          default: webhook
        status:
          type:
          - string
          enum:
          - active
          - inactive
          description: The status of the webhook
          title: WebhookStatus
        events:
          type:
          - array
          items:
            type:
            - string
            $ref: '#/components/schemas/EventType'
          minItems: 1
          description: The events to trigger the webhook
        url:
          type:
          - string
          format: uri
          description: The URL to send the webhook to
        secret:
          type: string
          description: The secret to verify the webhook signature. Only returned on Webhook creation.
          nullable: true
        metadata:
          default: {}
          description: The metadata of the webhook
          type:
          - object
          additionalProperties:
            type:
            - string
            maxLength: 1000
        createdAt:
          type:
          - string
          format: date-time
          description: The date and time the webhook was created
        updatedAt:
          type:
          - string
          format: date-time
          description: The date and time the webhook was last updated
      required:
      - id
      - object
      - status
      - events
      - url
      - secret
      - createdAt
      - updatedAt
    ListWebhooksResponse:
      type:
      - object
      properties:
        data:
          type:
          - array
          items:
            type:
            - object
            $ref: '#/components/schemas/Webhook'
          description: The list of webhooks
        hasMore:
          type:
          - boolean
          description: Whether there are more results to paginate through
        nextCursor:
          type: string
          description: The cursor to paginate through the next set of results
          nullable: true
      required:
      - data
      - hasMore
      - nextCursor
    CreateWebhookParameters:
      type:
      - object
      properties:
        events:
          type:
          - array
          items:
            type:
            - string
            $ref: '#/components/schemas/EventType'
          minItems: 1
          maxItems: 19
          description: The events to trigger the webhook
        url:
          type:
          - string
          format: uri
          description: The URL to send the webhook to
        metadata:
          description: Set of key-value pairs you want to associate with this object.
          type:
          - object
          additionalProperties:
            type:
            - string
            maxLength: 1000
      required:
      - events
      - url
    EventType:
      type: string
      enum:
      - webset.created
      - webset.deleted
      - webset.paused
      - webset.idle
      - webset.search.created
      - webset.search.canceled
      - webset.search.completed
      - webset.search.updated
      - import.created
      - import.completed
      - webset.item.created
      - webset.item.enriched
      - monitor.created
      - monitor.updated
      - monitor.deleted
      - monitor.run.created
      - monitor.run.completed
      - webset.export.created
      - webset.export.completed
    UpdateWebhookParameters:
      type:
      - object
      properties:
        events:
          type:
          - array
          items:
            type:
            - string
            $ref: '#/components/schemas/EventType'
          minItems: 1
          maxItems: 19
          description: The events to trigger the webhook
        url:
          type:
          - string
          format: uri
          description: The URL to send the webhook to
        metadata:
          description: Set of key-value pairs you want to associate with this object.
          type:
          - object
          additionalProperties:
            type:
            - string
            maxLength: 1000
  securitySchemes:
    apiKey:
      type: apiKey
      name: x-api-key
      in: header
      description: 'Pass your Exa API key in the x-api-key header. You can also authenticate with Authorization: Bearer <key>.'
    bearer:
      type: http
      scheme: bearer
      description: 'Pass your Exa API key in the x-api-key header. You can also authenticate with Authorization: Bearer <key>.'