Clarifeye Tools API

openapi: 3.2.0
info:
  title: Clarifeye Tools API
  version: 1.0.0
  contact:
    name: Clarifeye Support
  description: 'Operations tagged Tools across 2 of this provider''s published API definitions: clarifeye-backoffice-openapi-original.yaml, clarifeye-openapi-original.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://eu.app.clarifeye.ai/api/v1
  description: EU
- url: https://us.app.clarifeye.ai/api/v1
  description: US
security:
- BearerAuth: []
- TokenAuth: []
tags:
- name: Tools
  description: Execute configured AI tools with custom parameters
paths:
  /projects/{project_id}/tools/{tool_id}/run/:
    post:
      tags:
      - Tools
      summary: Run a tool
      description: 'Execute a configured tool with provided parameters.


        The request body varies based on the tool type. Most tools accept a `query` parameter

        and optional parameters like `top_k` for controlling result count.'
      operationId: runTool
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ToolId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolRunRequest'
            examples:
              retrieval:
                summary: Retrieval tool example
                value:
                  query: What are the key findings about revenue growth?
                  top_k: 10
              document_retrieval:
                summary: Document retrieval example
                value:
                  query: financial reports
                  top_k: 5
      responses:
        '200':
          description: Tool execution successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolRunResponse'
        '400':
          description: Invalid syntax or query errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Tool or index not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolError'
        '500':
          description: Database or internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolError'
    servers:
    - url: https://eu.app.clarifeye.ai/api/v1
      description: EU
    - url: https://us.app.clarifeye.ai/api/v1
      description: US
  /projects/{project_id}/tools/:
    get:
      tags:
      - Tools
      summary: List tools
      description: 'List all tools available to the project, including tools owned by the

        project (`category: local`) and tools imported from other projects

        (`category: imported`).


        Use the returned `id` together with

        `getToolParameters` to discover the

        request body schema for a given tool, then call

        `runTool` to execute it.'
      operationId: listTools
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: tool_type
        in: query
        description: Filter by tool type
        schema:
          $ref: '#/components/schemas/ToolType'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedResponse'
                - type: object
                  properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/Tool'
              example:
                count: 2
                next: null
                previous: null
                results:
                - id: 4f4a0a36-2c3d-4e6c-9a3b-2b1f0f1a2c11
                  name: Search financial chunks
                  description: Semantic search over chunks tagged as financial reports.
                  tool_type: retrieval
                  retrieval_mode: semantic-chunks
                  category: local
                  owner_project_id: 9c2b1c0a-7a1d-4d1d-8e3a-1d2b3c4d5e6f
                  owner_project_name: Finance Analytics
                  readonly: false
                  created_at: '2026-04-12T10:21:33Z'
                  updated_at: '2026-05-02T08:44:01Z'
                - id: c1a7f2e0-6e8f-4f0a-9d11-8b6e5d4c3b2a
                  name: Document retrieval (annual reports)
                  description: Retrieve documents by name or tag.
                  tool_type: document_retrieval
                  retrieval_mode: semantic-chunks
                  category: imported
                  owner_project_id: 11111111-2222-3333-4444-555555555555
                  owner_project_name: Shared Tools
                  readonly: true
                  created_at: '2026-03-08T15:02:11Z'
                  updated_at: '2026-04-22T11:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://eu.app.clarifeye.ai/api/v1
      description: EU
    - url: https://us.app.clarifeye.ai/api/v1
      description: US
  /projects/{project_id}/tools/{tool_id}/parameters/:
    get:
      tags:
      - Tools
      summary: Get tool parameters schema
      description: 'Return the JSON schema describing the parameters accepted by

        `runTool` for this tool.


        The schema is a list of parameter specs (`id`, `type`, `description`,

        `required`, and an optional `default`). The exact list depends on the

        tool''s `tool_type` and configuration — for example a retrieval tool

        configured with `auto_include` tags exposes an extra `included_tags`

        parameter.


        Use the `id` of each entry as the key in the JSON body sent to

        `runTool`.'
      operationId: getToolParameters
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ToolId'
      responses:
        '200':
          description: JSON schema describing the tool's run parameters
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ToolParameterSpec'
              examples:
                retrieval:
                  summary: Retrieval tool (search on chunks)
                  value:
                  - id: query
                    type: string
                    description: Query to search for chunks.
                    default: ''
                    required: false
                  - id: top_k
                    type: integer
                    description: 'Number of objects to retrieve. For initial search use the default top_k value : 10.'
                    default: 10
                    required: false
                document_retrieval:
                  summary: Document retrieval tool
                  value:
                  - id: mode
                    type: string
                    description: The mode to use. Can be name, content, tag, id.
                    required: true
                  - id: document_name_search_string
                    type: string
                    description: Search string within document names
                    required: true
                  - id: search_query_within_documents
                    type: string
                    description: The text used to identify parts of documents
                    required: true
                  - id: document_ids
                    type: string
                    description: A comma-separated list of ID strings (uuid) of documents to search within
                    required: true
                  - id: tag_list
                    type: string
                    description: A comma-separated list of tag IDs to search for documents
                    required: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://eu.app.clarifeye.ai/api/v1
      description: EU
    - url: https://us.app.clarifeye.ai/api/v1
      description: US
components:
  schemas:
    ToolRunResponse:
      type: array
      description: Array of tool execution results
      items:
        type: object
        description: Individual result object (structure varies by tool type)
        additionalProperties: true
    ToolError:
      type: object
      description: Error response from tool execution
      properties:
        error_type:
          type: string
          description: Category of the error
          example: syntax_error
        error_code:
          type: string
          description: Specific error code
          example: INVALID_QUERY
        status:
          type: string
          description: Error status
          example: error
        message:
          type: string
          description: Human-readable error message
          example: Invalid query syntax
    ToolRunRequest:
      type: object
      description: 'Request body for running a tool. Parameters vary by tool type.

        Most tools accept a `query` parameter and optional `top_k` for result count.

        '
      properties:
        query:
          type: string
          description: The search query or input for the tool
          example: What are the key findings about revenue growth?
        top_k:
          type: integer
          description: Maximum number of results to return
          default: 10
          example: 10
      additionalProperties: true
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      example:
        error: User not found
    ToolParameterSpec:
      type: object
      description: 'Specification for a single parameter accepted by a tool''s `run`

        endpoint. Use `id` as the key in the JSON body sent to

        [`runTool`](#operation/runTool).

        '
      properties:
        id:
          type: string
          description: Parameter name (used as the JSON key when calling `runTool`).
        type:
          type: string
          enum:
          - string
          - integer
          - number
          - boolean
          - array
          - object
          description: JSON type of the parameter value.
        description:
          type: string
          description: Human-readable description of the parameter.
        required:
          type: boolean
          description: Whether the parameter must be supplied when running the tool.
        default:
          description: Default value when the parameter is omitted. Type matches `type`.
      example:
        id: query
        type: string
        description: The search query for the tool.
        required: false
        default: ''
    PaginatedResponse:
      type: object
      properties:
        count:
          type: integer
          description: Total number of results
        next:
          type:
          - string
          - 'null'
          format: uri
          description: URL to next page of results
        previous:
          type:
          - string
          - 'null'
          format: uri
          description: URL to previous page of results
        results:
          type: array
          items: {}
    Tool:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        tool_type:
          $ref: '#/components/schemas/ToolType'
        retrieval_mode:
          type: string
          description: 'For tools with `tool_type: retrieval`, the specific retrieval

            variant (e.g. `semantic-chunks`, `semantic-objects`,

            `templated-query`). Ignored for other tool types.

            '
        category:
          type: string
          enum:
          - local
          - imported
          description: '- `local`: tool is owned by the current project.

            - `imported`: tool is owned by another project and exported into the current one.

            '
        owner_project_id:
          type: string
          format: uuid
          description: UUID of the project that owns the tool.
        owner_project_name:
          type:
          - string
          - 'null'
          description: Name of the project that owns the tool.
        readonly:
          type: boolean
          description: When true, the tool cannot be modified through the API.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      example:
        id: 4f4a0a36-2c3d-4e6c-9a3b-2b1f0f1a2c11
        name: Search financial chunks
        description: Semantic search over chunks tagged as financial reports.
        tool_type: retrieval
        retrieval_mode: semantic-chunks
        category: local
        owner_project_id: 9c2b1c0a-7a1d-4d1d-8e3a-1d2b3c4d5e6f
        owner_project_name: Finance Analytics
        readonly: false
        created_at: '2026-04-12T10:21:33Z'
        updated_at: '2026-05-02T08:44:01Z'
    ToolType:
      type: string
      enum:
      - retrieval
      - math
      - document_retrieval
      - data_statistics
      - websearch
      - sub_agent
      description: 'Category of tool, which controls how it is executed and what

        parameters it accepts. The `retrieval` family additionally exposes a

        `retrieval_mode` field (e.g. `semantic-chunks`, `semantic-objects`,

        `templated-query`).

        '
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: UUID of the project
      schema:
        type: string
        format: uuid
    ToolId:
      name: tool_id
      in: path
      required: true
      description: UUID of the tool
      schema:
        type: string
        format: uuid
    Limit:
      name: limit
      in: query
      description: Maximum number of results per page
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 1000
    Offset:
      name: offset
      in: query
      description: Number of results to skip for pagination
      schema:
        type: integer
        default: 0
        minimum: 0
  responses:
    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: You do not have permission to perform this action.
    Unauthorized:
      description: Unauthorized - missing or invalid authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Authentication credentials were not provided.
    NotFound:
      description: Not found - resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not found.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Use Authorization: Bearer <token>'
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Authorization: Token <token>'
x-refined-from:
- clarifeye-backoffice-openapi-original.yaml
- clarifeye-openapi-original.yaml