openapi: 3.1.0
info:
  contact:
    email: support@thecompaniesapi.com
    name: The Companies API
    url: https://www.thecompaniesapi.com
  description: An enrichment platform to search and retrieve information about companies
  termsOfService: https://www.thecompaniesapi.com/product/terms
  title: The Companies actions prompts API
  version: 2.0.0
servers:
- description: Production server
  url: https://api.thecompaniesapi.com
tags:
- name: prompts
paths:
  /v2/prompts:
    get:
      description: Fetch prompts history.
      operationId: fetchPrompts
      tags:
      - prompts
      security:
      - apiKey: []
      parameters:
      - schema:
          type: number
        required: false
        name: companyId
        in: query
      - schema:
          type: string
          enum:
          - analytics
          - api
          - companies
          - company
          - documentation
          - enrichment
          - landing
          - list
          - similarity
        required: false
        name: context
        in: query
      - schema:
          type: string
          enum:
          - ask
          - cleanup
          - enrich
          - product
          - search
          - similar
        required: false
        name: feature
        in: query
      - schema:
          type: number
        required: false
        name: limit
        in: query
      - schema:
          type: number
        required: false
        name: listId
        in: query
      - schema:
          type: string
          enum:
          - small
          - large
        required: false
        name: model
        in: query
      - schema:
          type: number
        required: false
        name: page
        in: query
      - schema:
          type: string
        required: false
        name: prompt
        in: query
      - schema:
          type: string
        required: false
        name: search
        in: query
      - schema:
          type: number
        required: false
        name: size
        in: query
      responses:
        '200':
          description: Fetch prompts history.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                  prompts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Prompt'
                required:
                - meta
                - prompts
        '401':
          description: The error message
          content:
            application/json:
              schema:
                type: object
                properties:
                  details: {}
                  messages:
                    type: string
                    enum:
                    - tokenNotFound
                    - invalidApiSecret
                    - missingApiSecret
                    - userNotAuthenticated
                  status:
                    type: number
                    minimum: 400
                    maximum: 511
                required:
                - messages
                - status
  /v2/prompts/{promptId}:
    delete:
      description: Delete a prompt.
      operationId: deletePrompt
      tags:
      - prompts
      security:
      - apiKey: []
      parameters:
      - schema:
          type: number
        required: true
        name: promptId
        in: path
      responses:
        '200':
          description: Delete a prompt.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '400':
          description: The error message
          content:
            application/json:
              schema:
                type: object
                properties:
                  details: {}
                  messages:
                    type: string
                    enum:
                    - promptNotFound
                  status:
                    type: number
                    minimum: 400
                    maximum: 511
                required:
                - messages
                - status
        '401':
          description: The error message
          content:
            application/json:
              schema:
                type: object
                properties:
                  details: {}
                  messages:
                    type: string
                    enum:
                    - tokenNotFound
                    - invalidApiSecret
                    - missingApiSecret
                    - userNotAuthenticated
                  status:
                    type: number
                    minimum: 400
                    maximum: 511
                required:
                - messages
                - status
        '403':
          description: The error message
          content:
            application/json:
              schema:
                type: object
                properties:
                  details: {}
                  messages:
                    type: string
                    enum:
                    - userCurrentTeamIsNotInstanceOwner
                  status:
                    type: number
                    minimum: 400
                    maximum: 511
                required:
                - messages
                - status
  /v2/prompts/product:
    post:
      description: Query the product prompt.
      operationId: productPrompt
      tags:
      - prompts
      security:
      - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                companyId:
                  type: number
                context:
                  type: string
                  enum:
                  - analytics
                  - api
                  - companies
                  - company
                  - documentation
                  - enrichment
                  - landing
                  - list
                  - similarity
                feature:
                  type: string
                  enum:
                  - ask
                  - cleanup
                  - enrich
                  - product
                  - search
                  - similar
                force:
                  type: boolean
                listId:
                  type: number
                model:
                  type: string
                  enum:
                  - small
                  - large
                prompt:
                  type: string
              required:
              - prompt
      responses:
        '200':
          description: Query the product prompt.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                  prompt:
                    $ref: '#/components/schemas/Prompt'
                  response:
                    anyOf:
                    - type: object
                      properties:
                        all:
                          type: boolean
                        cost:
                          type: number
                        count:
                          type: number
                        domain:
                          type: string
                        error:
                          type: string
                        action:
                          type: object
                          properties:
                            cost:
                              type: number
                            data:
                              type: object
                              properties:
                                answer:
                                  $ref: '#/components/schemas/LLMAnswer'
                                domains:
                                  type: array
                                  items:
                                    type: string
                                fields:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      description:
                                        type: string
                                      key:
                                        type: string
                                      type:
                                        type: string
                                        enum:
                                        - array|boolean
                                        - array|number
                                        - array|string
                                        - boolean
                                        - number
                                        - string
                                      values:
                                        type: array
                                        items:
                                          type: string
                                    required:
                                    - key
                                    - type
                                job:
                                  type: string
                                  enum:
                                  - ask-list
                                query:
                                  type: array
                                  items:
                                    $ref: '#/components/schemas/SegmentationCondition'
                                question:
                                  type: string
                              required:
                              - answer
                              - fields
                              - job
                              - question
                            listId:
                              type: number
                            promptId:
                              type: number
                            status:
                              type: string
                              enum:
                              - pending
                            type:
                              type: string
                              enum:
                              - jobs:request
                          required:
                          - promptId
                          - status
                          - type
                        answer:
                          type: object
                          properties:
                            explanation:
                              type: string
                            output:
                              type: object
                              additionalProperties: {}
                            score:
                              type: number
                          required:
                          - output
                          - score
                    - type: object
                      properties:
                        all:
                          type: boolean
                        cost:
                          type: number
                        count:
                          type: number
                        domain:
                          type: string
                        error:
                          type: string
                        action:
                          type: object
                          properties:
                            cost:
                              type: number
                              enum:
                              - 0
                            data:
                              type: object
                              properties:
                                domains:
                                  type: array
                                  items:
                                    type: string
                                job:
                                  type: string
                                  enum:
                                  - cleanup-list
                                query:
                                  type: array
                                  items:
                                    $ref: '#/components/schemas/SegmentationCondition'
                              required:
                              - job
                            listId:
                              type: number
                            promptId:
                              type: number
                            status:
                              type: string
                              enum:
                              - pending
                            type:
                              type: string
                              enum:
                              - jobs:request
                          required:
                          - promptId
                          - status
                          - type
                    - type: object
                      properties:
                        all:
                          type: boolean
                        cost:
                          type: number
                        count:
                          type: number
                        domain:
                          type: string
                        error:
                          type: string
                        action:
                          type: object
                          properties:
                            cost:
                              type: number
                            data:
                              type: object
                              properties:
                                domains:
                                  type: array
                                  items:
                                    type: string
                                job:
                                  type: string
                                  enum:
                                  - enrich-companies
                                  - enrich-list
                                query:
                                  type: array
                                  items:
                                    $ref: '#/components/schemas/SegmentationCondition'
                              required:
                              - job
                            listId:
                              type: number
                            promptId:
                              type: number
                            status:
                              type: string
                              enum:
                              - pending
                            type:
                              type: string
                              enum:
                              - jobs:request
                          required:
                          - data
                          - promptId
                          - status
                          - type
                    - type: object
                      properties:
                        all:
                          type: boolean
                        cost:
                          type: number
                        count:
                          type: number
                        domain:
                          type: string
                        error:
                          type: string
                        domains:
                          type: array
                          items:
                            type: string
                        listId:
                          type: number
                        query:
                          type: array
                          items:
                            $ref: '#/components/schemas/SegmentationCondition'
                    - type: object
                      properties:
                        all:
                          type: boolean
                        cost:
                          type: number
                        count:
                          type: number
                        domain:
                          type: string
                        error:
                          type: string
                        domains:
                          type: array
                          items:
                            type: string
                required:
                - meta
                - prompt
                - response
        '401':
          description: The error message
          content:
            application/json:
              schema:
                type: object
                properties:
                  details: {}
                  messages:
                    type: string
                    enum:
                    - tokenNotFound
                    - invalidApiSecret
                    - missingApiSecret
                    - userNotAuthenticated
                  status:
                    type: number
                    minimum: 400
                    maximum: 511
                required:
                - messages
                - status
        '403':
          description: The error message
          content:
            application/json:
              schema:
                type: object
                properties:
                  details: {}
                  messages:
                    type: string
                    enum:
                    - noCreditsRemaining
                  status:
                    type: number
                    minimum: 400
                    maximum: 511
                required:
                - messages
                - status
  /v2/prompts/segmentation:
    post:
      description: Convert a query to a segmentation.
      operationId: promptToSegmentation
      tags:
      - prompts
      security:
      - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                context:
                  type: string
                  enum:
                  - analytics
                  - api
                  - companies
                  - company
                  - documentation
                  - enrichment
                  - landing
                  - list
                  - similarity
                force:
                  type: boolean
                listId:
                  type: number
                model:
                  type: string
                  enum:
                  - small
                  - large
                prompt:
                  type: string
              required:
              - prompt
      responses:
        '200':
          description: Convert a query to a segmentation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                  prompt:
                    $ref: '#/components/schemas/Prompt'
                  response:
                    type: object
                    properties:
                      all:
                        type: boolean
                      cost:
                        type: number
                      count:
                        type: number
                      domain:
                        type: string
                      error:
                        type: string
                      domains:
                        type: array
                        items:
                          type: string
                      listId:
                        type: number
                      query:
                        type: array
                        items:
                          $ref: '#/components/schemas/SegmentationCondition'
                required:
                - meta
                - prompt
                - response
        '401':
          description: The error message
          content:
            application/json:
              schema:
                type: object
                properties:
                  details: {}
                  messages:
                    type: string
                    enum:
                    - tokenNotFound
                    - invalidApiSecret
                    - missingApiSecret
                    - userNotAuthenticated
                  status:
                    type: number
                    minimum: 400
                    maximum: 511
                required:
                - messages
                - status
components:
  schemas:
    LLMAnswer:
      type: object
      properties:
        companyId:
          type: number
        explanation:
          type: string
        fields:
          type: array
          items:
            type: object
            properties:
              description:
                type: string
              key:
                type: string
              type:
                type: string
                enum:
                - array|boolean
                - array|number
                - array|string
                - boolean
                - number
                - string
              values:
                type: array
                items:
                  type: string
            required:
            - key
            - type
        grounded:
          type: boolean
        output:
          type: object
          additionalProperties: {}
        question:
          type: string
        score:
          type: number
      required:
      - companyId
      - output
      - question
      - score
      description: An answer from a query made to the LLM.
    PaginationMeta:
      type: object
      properties:
        cost:
          type: number
        credits:
          type: number
        currentPage:
          type: number
        firstPage:
          type: number
        freeRequest:
          type: boolean
        lastPage:
          type: number
        maxScrollResultsReached:
          type: boolean
        perPage:
          type: number
        total:
          type: number
      required:
      - cost
      - credits
      - currentPage
      - firstPage
      - freeRequest
      - lastPage
      - perPage
      - total
      description: Metadata about a paginated or billed response.
    SegmentationCondition:
      type: object
      properties:
        attribute:
          type: string
          enum:
          - about.businessType
          - about.industries
          - about.industry
          - about.name
          - about.totalEmployees
          - about.yearFounded
          - ai.search
          - analytics.monthlyVisitors
          - apps
          - codes.naics
          - codes.sic
          - contacts
          - domain.domain
          - domain.tld
          - finances.revenue
          - finances.stockExchange
          - locations.headquarters.city.code
          - locations.headquarters.continent.code
          - locations.headquarters.country.code
          - locations.headquarters.county.code
          - locations.headquarters.state.code
          - meta.listIds
          - meta.score
          - meta.syncedAt
          - socials
          - socials.linkedin.id
          - technologies.active
          - technologies.categories
          - urls
        blockedOperator:
          type: boolean
        operator:
          type: string
          enum:
          - and
          - or
        sign:
          type: string
          enum:
          - equals
          - exactEquals
          - greater
          - lower
          - notEquals
        values:
          type: array
          items:
            anyOf:
            - type: string
            - type: number
      required:
      - attribute
      - operator
      - sign
      - values
      description: A condition for our platform segmentation engine.
    Prompt:
      type: object
      properties:
        companyId:
          type: number
        context:
          type: string
          enum:
          - analytics
          - api
          - companies
          - company
          - documentation
          - enrichment
          - landing
          - list
          - similarity
        createdAt:
          type: string
        data:
          type: object
          properties:
            all:
              type: boolean
            count:
              type: number
            domains:
              type: array
              items:
                type: string
            explain:
              type: boolean
            fields:
              type: array
              items:
                type: object
                properties:
                  description:
                    type: string
                  key:
                    type: string
                  type:
                    type: string
                    enum:
                    - array|boolean
                    - array|number
                    - array|string
                    - boolean
                    - number
                    - string
                  values:
                    type: array
                    items:
                      type: string
                required:
                - key
                - type
            model:
              type: string
              enum:
              - small
              - large
            names:
              type: array
              items:
                type: string
            query:
              type: array
              items:
                $ref: '#/components/schemas/SegmentationCondition'
            question:
              type: string
            segmentation:
              type: boolean
        feature:
          type: string
          enum:
          - ask
          - cleanup
          - enrich
          - product
          - search
          - similar
        hits:
          type: number
        id:
          type: number
        model:
          type: string
          enum:
          - small
          - large
        prompt:
          type: string
        promptKey:
          type: string
        response:
          anyOf:
          - type: object
            properties:
              all:
                type: boolean
              cost:
                type: number
              count:
                type: number
              domain:
                type: string
              error:
                type: string
              action:
                type: object
                properties:
                  cost:
                    type: number
                  data:
                    type: object
                    properties:
                      answer:
                        $ref: '#/components/schemas/LLMAnswer'
                      domains:
                        type: array
                        items:
                          type: string
                      fields:
                        type: array
                        items:
                          type: object
                          properties:
                            description:
                              type: string
                            key:
                              type: string
                            type:
                              type: string
                              enum:
                              - array|boolean
                              - array|number
                              - array|string
                              - boolean
                              - number
                              - string
                            values:
                              type: array
                              items:
                                type: string
                          required:
                          - key
                          - type
                      job:
                        type: string
                        enum:
                        - ask-list
                      query:
                        type: array
                        items:
                          $ref: '#/components/schemas/SegmentationCondition'
                      question:
                        type: string
                    required:
                    - answer
                    - fields
                    - job
                    - question
                  listId:
                    type: number
                  promptId:
                    type: number
                  status:
                    type: string
                    enum:
                    - pending
                  type:
                    type: string
                    enum:
                    - jobs:request
                required:
                - promptId
                - status
                - type
              answer:
                type: object
                properties:
                  explanation:
                    type: string
                  output:
                    type: object
                    additionalProperties: {}
                  score:
                    type: number
                required:
                - output
                - score
          - type: object
            properties:
              all:
                type: boolean
              cost:
                type: number
              count:
                type: number
              domain:
                type: string
              error:
                type: string
              action:
                type: object
                properties:
                  cost:
                    type: number
                    enum:
                    - 0
                  data:
                    type: object
                    properties:
                      domains:
                        type: array
                        items:
                          type: string
                      job:
                        type: string
                        enum:
                        - cleanup-list
                      query:
                        type: array
                        items:
                          $ref: '#/components/schemas/SegmentationCondition'
                    required:
                    - job
                  listId:
                    type: number
                  promptId:
                    type: number
                  status:
                    type: string
                    enum:
                    - pending
                  type:
                    type: string
                    enum:
                    - jobs:request
                required:
                - promptId
                - status
                - type
          - type: object
            properties:
              all:
                type: boolean
              cost:
                type: number
              count:
                type: number
              domain:
                type: string
              error:
                type: string
              action:
                type: object
                properties:
                  cost:
                    type: number
                  data:
                    type: object
                    properties:
                      domains:
                        type: array
                        items:
                          type: string
                      job:
                        type: string
                        enum:
                        - enrich-companies
                        - enrich-list
                      query:
                        type: array
                        items:
                          $ref: '#/components/schemas/SegmentationCondition'
                    required:
                    - job
                  listId:
                    type: number
                  promptId:
                    type: number
                  status:
                    type: string
                    enum:
                    - pending
                  type:
                    type: string
                    enum:
                    - jobs:request
                required:
                - data
                - promptId
                - status
                - type
          - type: object
            properties:
              all:
                type: boolean
              cost:
                type: number
              count:
                type: number
              domain:
                type: string
              error:
                type: string
              domains:
                type: array
                items:
                  type: string
              listId:
                type: number
              query:
                type: array
                items:
                  $ref: '#/components/schemas/SegmentationCondition'
          - type: object
            properties:
              all:
                type: boolean
              cost:
                type: number
              count:
                type: number
              domain:
                type: string
              error:
                type: string
              domains:
                type: array
                items:
                  type: string
        updatedAt:
          type: string
      required:
      - context
      - id
      - prompt
      - promptKey
      description: A natural language request made to the platform resolving to a specific action or search segment.
  securitySchemes:
    apiKey:
      description: The API key to use for authentication, you can get it from your API tokens page.
      in: header
      name: Authorization
      type: apiKey
externalDocs:
  description: The Companies API Documentation
  url: https://www.thecompaniesapi.com/docs