Exa Items API

openapi: 3.1.0
info:
  title: Exa Agent Items 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: Items
paths:
  /v0/websets/{webset}/items/{id}:
    servers:
    - url: https://api.exa.ai/websets
    get:
      description: Returns a Webset Item.
      operationId: websets-items-get
      parameters:
      - name: webset
        required: true
        in: path
        description: The id or externalId of the Webset
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The id of the Webset item
        schema:
          type: string
      responses:
        '200':
          description: Webset Item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebsetItem'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
      summary: Get an Item
      tags:
      - Items
      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 item = await exa.websets.items.get("webset_id", "item_id");


          console.log(`Item: ${item.id} - ${item.properties.name}`);'
      - lang: python
        label: Python
        source: '# pip install exa-py

          from exa_py import Exa


          exa = Exa("YOUR_EXA_API_KEY")


          item = exa.websets.items.get("webset_id", "item_id")


          print(f"Item: {item.id} - {item.properties.name}")'
    delete:
      description: 'Deletes an Item from the Webset.


        This will cancel any enrichment process for it.'
      operationId: websets-items-delete
      parameters:
      - name: webset
        required: true
        in: path
        description: The id or externalId of the Webset
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The id of the Webset item
        schema:
          type: string
      responses:
        '200':
          description: Webset Item deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebsetItem'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
      summary: Delete an Item
      tags:
      - Items
      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.items.delete("webset_id", "item_id");


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

          from exa_py import Exa


          exa = Exa("YOUR_EXA_API_KEY")


          exa.websets.items.delete("webset_id", "item_id")


          print("Item deleted successfully")'
  /v0/websets/{webset}/items:
    servers:
    - url: https://api.exa.ai/websets
    get:
      description: 'Returns a list of Webset Items.


        You can paginate through the Items using the `cursor` parameter.'
      operationId: websets-items-list
      parameters:
      - name: webset
        required: true
        in: path
        description: The id or externalId of the Webset
        schema:
          type: string
      - 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: 100
          default: 20
          type: number
      - name: sourceId
        required: false
        in: query
        description: The id of the source
        schema:
          type: string
      responses:
        '200':
          description: Webset Items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWebsetItemResponse'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
      summary: List all Items for a Webset
      tags:
      - Items
      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 items = await exa.websets.items.list(\"webset_id\", {\n  limit: 20,\n});\n\nconsole.log(`Found ${items.data.length} items`);\nitems.data.forEach((item) => {\n  console.log(`- ${item.id}: ${item.properties.name}`);\n});"
      - lang: python
        label: Python
        source: "# pip install exa-py\nfrom exa_py import Exa\n\nexa = Exa(\"YOUR_EXA_API_KEY\")\n\nitems = exa.websets.items.list(\"webset_id\", limit=20)\n\nprint(f\"Found {len(items.data)} items\")\nfor item in items.data:\n    print(f\"- {item.id}: {item.properties.name}\")"
components:
  schemas:
    WebsetItemCompanyProperties:
      type:
      - object
      properties:
        type:
          type: string
          const: company
          default: company
        url:
          type:
          - string
          format: uri
          description: The URL of the company website
        description:
          type:
          - string
          description: Short description of the relevance of the company
        content:
          type: string
          description: The text content of the company website
          nullable: true
        company:
          type:
          - object
          properties:
            name:
              type:
              - string
              description: The name of the company
            location:
              type: string
              description: The main location of the company
              nullable: true
            employees:
              type: number
              description: The number of employees of the company
              nullable: true
            industry:
              type: string
              description: The industry of the company
              nullable: true
            about:
              type: string
              description: A short description of the company
              nullable: true
            logoUrl:
              type: string
              format: uri
              description: The logo URL of the company
              nullable: true
            foundedYear:
              type: number
              description: The year the company was founded
              nullable: true
            headquarters:
              type: object
              nullable: true
              description: The structured headquarters address of the company
              properties:
                address:
                  type: string
                  description: The street address of the headquarters
                  nullable: true
                city:
                  type: string
                  description: The city of the headquarters
                  nullable: true
                state:
                  type: string
                  description: The state or region of the headquarters
                  nullable: true
                postalCode:
                  type: string
                  description: The postal code of the headquarters
                  nullable: true
                country:
                  type: string
                  description: The country of the headquarters
                  nullable: true
                countryCode:
                  type: string
                  description: The ISO country code of the headquarters
                  nullable: true
              required:
              - address
              - city
              - state
              - postalCode
              - country
              - countryCode
              title: WebsetItemCompanyHeadquarters
            financials:
              type: object
              nullable: true
              description: Financial information about the company
              properties:
                revenueAnnual:
                  type: number
                  description: The annual revenue of the company (USD)
                  nullable: true
                fundingTotal:
                  type: number
                  description: The total funding raised by the company (USD)
                  nullable: true
                fundingLatestRound:
                  type: object
                  nullable: true
                  description: The latest funding round
                  properties:
                    name:
                      type: string
                      description: The name of the funding round (e.g. Series A)
                      nullable: true
                    date:
                      type: string
                      description: The date of the funding round
                      nullable: true
                    amount:
                      type: number
                      description: The amount raised in the funding round (USD)
                      nullable: true
                  required:
                  - name
                  - date
                  - amount
                  title: WebsetItemCompanyFundingRound
              required:
              - revenueAnnual
              - fundingTotal
              - fundingLatestRound
              title: WebsetItemCompanyFinancials
            webTraffic:
              type: object
              nullable: true
              description: Web traffic metrics for the company
              properties:
                visitsMonthly:
                  type: number
                  description: The estimated monthly website visits
                  nullable: true
                uniqueVisitors:
                  type: number
                  description: The estimated monthly unique visitors
                  nullable: true
              required:
              - visitsMonthly
              - uniqueVisitors
              title: WebsetItemCompanyWebTraffic
          required:
          - name
          - location
          - employees
          - industry
          - about
          - logoUrl
          - foundedYear
          - headquarters
          - financials
          - webTraffic
          title: WebsetItemCompanyPropertiesFields
      required:
      - type
      - url
      - description
      - content
      - company
    WebsetEnrichmentFormat:
      type: string
      enum:
      - text
      - date
      - number
      - options
      - email
      - phone
      - url
    WebsetItemArticleProperties:
      type:
      - object
      properties:
        type:
          type: string
          const: article
          default: article
        url:
          type:
          - string
          format: uri
          description: The URL of the article
        description:
          type:
          - string
          description: Short description of the relevance of the article
        content:
          type: string
          description: The text content for the article
          nullable: true
        article:
          type:
          - object
          properties:
            title:
              type: string
              description: The title of the article
              nullable: true
            author:
              type: string
              description: The author(s) of the article
              nullable: true
            publishedAt:
              type: string
              description: The date and time the article was published
              nullable: true
          required:
          - title
          - author
          - publishedAt
          title: WebsetItemArticlePropertiesFields
      required:
      - type
      - url
      - description
      - content
      - article
    WebsetItemEvaluation:
      type:
      - object
      properties:
        criterion:
          type:
          - string
          description: The description of the criterion
        reasoning:
          type:
          - string
          description: The reasoning for the result of the evaluation
        satisfied:
          type:
          - string
          enum:
          - 'yes'
          - 'no'
          - unclear
          description: The satisfaction of the criterion
        references:
          default: []
          type:
          - array
          items:
            type:
            - object
            properties:
              title:
                type: string
                description: The title of the reference
                nullable: true
              snippet:
                type: string
                description: The relevant snippet of the reference content
                nullable: true
              url:
                type:
                - string
                format: uri
                description: The URL of the reference
            required:
            - title
            - snippet
            - url
          description: The references used to generate the result.
      required:
      - criterion
      - reasoning
      - satisfied
    WebsetItemCustomProperties:
      type:
      - object
      properties:
        type:
          type: string
          const: custom
          default: custom
        url:
          type:
          - string
          format: uri
          description: The URL of the Item
        description:
          type:
          - string
          description: Short description of the Item
        content:
          type: string
          description: The text content of the Item
          nullable: true
        custom:
          type:
          - object
          properties:
            title:
              type: string
              description: The title of the website
              nullable: true
            author:
              type: string
              description: The author(s) of the website
              nullable: true
            publishedAt:
              type: string
              description: The date and time the website was published
              nullable: true
          required:
          - title
          - author
          - publishedAt
          title: WebsetItemCustomPropertiesFields
      required:
      - type
      - url
      - description
      - content
      - custom
    WebsetItem:
      type:
      - object
      properties:
        id:
          type:
          - string
          description: The unique identifier for the Webset Item
        object:
          type: string
          const: webset_item
          default: webset_item
        source:
          type:
          - string
          enum:
          - search
          - import
          description: The source of the Item
        sourceId:
          type:
          - string
          description: The unique identifier for the source
        sourceEntityId:
          type:
          - string
          description: The original identifier used to resolve this item (e.g., email, name, or URL). Only relevant when the source is import.
        websetId:
          type:
          - string
          description: The unique identifier for the Webset this Item belongs to.
        properties:
          oneOf:
          - type:
            - object
            $ref: '#/components/schemas/WebsetItemPersonProperties'
            title: Person
          - type:
            - object
            $ref: '#/components/schemas/WebsetItemCompanyProperties'
            title: Company
          - type:
            - object
            $ref: '#/components/schemas/WebsetItemArticleProperties'
            title: Article
          - type:
            - object
            $ref: '#/components/schemas/WebsetItemResearchPaperProperties'
            title: Research Paper
          - type:
            - object
            $ref: '#/components/schemas/WebsetItemCustomProperties'
            title: Custom
          description: The properties of the Item
        evaluations:
          type:
          - array
          items:
            type:
            - object
            $ref: '#/components/schemas/WebsetItemEvaluation'
          description: The criteria evaluations of the item
        enrichments:
          type: array
          items:
            type:
            - object
            $ref: '#/components/schemas/EnrichmentResult'
          description: The enrichments results of the Webset item
          nullable: true
        createdAt:
          type:
          - string
          format: date-time
          description: The date and time the item was created
        updatedAt:
          type:
          - string
          format: date-time
          description: The date and time the item was last updated
      required:
      - id
      - object
      - source
      - sourceId
      - websetId
      - properties
      - evaluations
      - enrichments
      - createdAt
      - updatedAt
    WebsetItemPersonProperties:
      type:
      - object
      properties:
        type:
          type: string
          const: person
          default: person
        url:
          type:
          - string
          format: uri
          description: The URL of the person profile
        description:
          type:
          - string
          description: Short description of the relevance of the person
        person:
          type:
          - object
          properties:
            name:
              type:
              - string
              description: The name of the person
            location:
              type: string
              description: The location of the person
              nullable: true
            position:
              type: string
              description: The current work position of the person
              nullable: true
            company:
              type: object
              properties:
                name:
                  type:
                  - string
                  description: The name of the company
                location:
                  type: string
                  description: The location the person is working at the company
                  nullable: true
              required:
              - name
              - location
              title: WebsetItemPersonCompanyPropertiesFields
              nullable: true
            pictureUrl:
              type: string
              format: uri
              description: The image URL of the person
              nullable: true
          required:
          - name
          - location
          - position
          - company
          - pictureUrl
          title: WebsetItemPersonPropertiesFields
      required:
      - type
      - url
      - description
      - person
    EnrichmentResult:
      type:
      - object
      properties:
        object:
          type: string
          const: enrichment_result
          default: enrichment_result
        status:
          type:
          - string
          enum:
          - pending
          - completed
          - canceled
          description: The status of the enrichment result.
        format:
          type:
          - string
          $ref: '#/components/schemas/WebsetEnrichmentFormat'
        result:
          type: array
          items:
            type:
            - string
          description: The result of the enrichment.
          nullable: true
        reasoning:
          type: string
          description: The reasoning for the result when an Agent is used.
          nullable: true
        references:
          type:
          - array
          items:
            type:
            - object
            properties:
              title:
                type: string
                description: The title of the reference
                nullable: true
              snippet:
                type: string
                description: The relevant snippet of the reference content
                nullable: true
              url:
                type:
                - string
                format: uri
                description: The URL of the reference
            required:
            - title
            - snippet
            - url
          description: The references used to generate the result.
        enrichmentId:
          type:
          - string
          description: The id of the Enrichment that generated the result
      required:
      - object
      - status
      - format
      - result
      - reasoning
      - references
      - enrichmentId
    WebsetItemResearchPaperProperties:
      type:
      - object
      properties:
        type:
          type: string
          const: research_paper
          default: research_paper
        url:
          type:
          - string
          format: uri
          description: The URL of the research paper
        description:
          type:
          - string
          description: Short description of the relevance of the research paper
        content:
          type: string
          description: The text content of the research paper
          nullable: true
        researchPaper:
          type:
          - object
          properties:
            title:
              type: string
              description: The title of the research paper
              nullable: true
            author:
              type: string
              description: The author(s) of the research paper
              nullable: true
            publishedAt:
              type: string
              description: The date and time the research paper was published
              nullable: true
          required:
          - title
          - author
          - publishedAt
          title: WebsetItemResearchPaperPropertiesFields
      required:
      - type
      - url
      - description
      - content
      - researchPaper
    ListWebsetItemResponse:
      type:
      - object
      properties:
        data:
          type:
          - array
          items:
            type:
            - object
            $ref: '#/components/schemas/WebsetItem'
          description: The list of webset items
        hasMore:
          type:
          - boolean
          description: Whether there are more Items to paginate through
        nextCursor:
          type: string
          description: The cursor to paginate through the next set of Items
          nullable: true
      required:
      - data
      - hasMore
      - nextCursor
  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>.'