Hlix Tools API

openapi: 3.2.0
info:
  description: Explore the Hlix API for projects, agent teams, and delivery workflows. Authenticate with `x-api-key` and select a Workspace with `X-Organization-Id`. Session-only operations require a signed-in user session. Authentication setup.
  title: reference Tools API
  version: 1.0.0
servers:
- url: https://server.hlix.ai
  description: API server
security:
- apiKey: []
- sessionCookie: []
tags:
- description: Shared tool discovery, durable invocation and usage receipts.
  name: Tools
paths:
  /v1/api/tool-calls:
    get:
      operationId: listToolCalls
      parameters:
      - description: Filter by project.
        in: query
        name: projectId
        required: false
        schema:
          type: string
      - description: 1–100, defaults to 30.
        in: query
        name: limit
        required: false
        schema:
          type: string
      - description: Opaque nextCursor from the previous page.
        in: query
        name: cursor
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolCallList'
          description: Newest first, with stable keyset pagination.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
      summary: List recent workspace tool invocations
      tags:
      - Tools
  /v1/api/tool-calls/{callId}:
    get:
      operationId: getToolCall
      parameters:
      - in: path
        name: callId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolCall'
          description: Execution and cost settle independently. Native accounting belongs to the named service; null actual costs are not zero.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such tool or call in this workspace.
      summary: Read a persisted tool result and cost status
      tags:
      - Tools
  /v1/api/tools:
    get:
      operationId: searchTools
      parameters:
      - description: Search text, up to 500 characters.
        in: query
        name: query
        required: false
        schema:
          type: string
      - description: Provider filter.
        in: query
        name: provider
        required: false
        schema:
          type: string
      - description: 1–100, defaults to 30.
        in: query
        name: limit
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolSearchResult'
          description: Native and upstream tool descriptors. Remote totals may be unknown.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
      summary: Search available tools and inspect funding readiness
      tags:
      - Tools
  /v1/api/tools/connections/treg:
    delete:
      operationId: removeToolConnection
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolConnection'
          description: The connection was removed. Owner or admin only.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
      summary: Remove a workspace Treg connection
      tags:
      - Tools
    get:
      operationId: getToolConnection
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolConnection'
          description: Credential presence, never the token.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
      summary: Read safe Treg connection state
      tags:
      - Tools
    put:
      operationId: saveToolConnection
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveToolConnection'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolConnection'
          description: The encrypted connection was saved. Owner or admin only.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`).
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
      summary: Save a workspace Treg connection
      tags:
      - Tools
  /v1/api/tools/{toolId}:
    get:
      operationId: describeTool
      parameters:
      - in: path
        name: toolId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolDescriptor'
          description: Tool descriptor.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such tool or call in this workspace.
      summary: Read the accepted input schema and execution policy
      tags:
      - Tools
  /v1/api/tools/{toolId}/call:
    post:
      operationId: callTool
      parameters:
      - in: path
        name: toolId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolCallInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolCall'
          description: 'Same idempotency key and request: the existing invocation.'
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolCall'
          description: New invocation persisted before provider dispatch.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`).
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Insufficient workspace spending headroom for this reservation.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such tool or call in this workspace.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: This key already identifies a different request, or the selected connection is unavailable.
      summary: Create or revisit a durable tool invocation
      tags:
      - Tools
components:
  schemas:
    ApiError:
      additionalProperties: {}
      properties:
        error:
          type: string
      required:
      - error
      type: object
    ToolSearchResult:
      properties:
        tools:
          items:
            properties:
              accountingOwner:
                enum:
                - router
                - ai
                - web
                - external
                type: string
              availability:
                properties:
                  ready:
                    type: boolean
                  reason:
                    anyOf:
                    - enum:
                      - connection_required
                      - platform_unavailable
                      - provider_disabled
                      - unsupported_contract
                      - authorization_required
                      - discovery_required
                      type: string
                    - type: 'null'
                required:
                - ready
                - reason
                type: object
              description:
                type: string
              fundingModes:
                items:
                  enum:
                  - auto
                  - hlix
                  - organization
                  type: string
                type: array
              id:
                type: string
              inputSchema:
                additionalProperties: {}
                propertyNames:
                  type: string
                type: object
              name:
                type: string
              provider:
                type: string
              retry:
                properties:
                  ambiguousDispatch:
                    const: reconcile_only
                    type: string
                  sameKey:
                    const: returns_existing_call
                    type: string
                required:
                - sameKey
                - ambiguousDispatch
                type: object
            required:
            - id
            - name
            - description
            - provider
            - inputSchema
            - accountingOwner
            - fundingModes
            - availability
            - retry
            type: object
          type: array
        total:
          anyOf:
          - maximum: 9007199254740991
            minimum: 0
            type: integer
          - type: 'null'
        truncated:
          type: boolean
      required:
      - tools
      - total
      - truncated
      type: object
    ToolDescriptor:
      properties:
        accountingOwner:
          enum:
          - router
          - ai
          - web
          - external
          type: string
        availability:
          properties:
            ready:
              type: boolean
            reason:
              anyOf:
              - enum:
                - connection_required
                - platform_unavailable
                - provider_disabled
                - unsupported_contract
                - authorization_required
                - discovery_required
                type: string
              - type: 'null'
          required:
          - ready
          - reason
          type: object
        description:
          type: string
        fundingModes:
          items:
            enum:
            - auto
            - hlix
            - organization
            type: string
          type: array
        id:
          type: string
        inputSchema:
          additionalProperties: {}
          propertyNames:
            type: string
          type: object
        name:
          type: string
        provider:
          type: string
        retry:
          properties:
            ambiguousDispatch:
              const: reconcile_only
              type: string
            sameKey:
              const: returns_existing_call
              type: string
          required:
          - sameKey
          - ambiguousDispatch
          type: object
      required:
      - id
      - name
      - description
      - provider
      - inputSchema
      - accountingOwner
      - fundingModes
      - availability
      - retry
      type: object
    ToolConnection:
      properties:
        enabled:
          type: boolean
        hasApiKey:
          type: boolean
        organizationId:
          type:
          - string
          - 'null'
        platformAvailable:
          type: boolean
        provider:
          const: treg
          type: string
      required:
      - provider
      - hasApiKey
      - enabled
      - organizationId
      - platformAvailable
      type: object
    ToolCall:
      properties:
        accountingOwner:
          enum:
          - router
          - ai
          - web
          - external
          type: string
        billedMicros:
          anyOf:
          - format: int64
            maximum: 9007199254740991
            minimum: 0
            type: integer
          - type: 'null'
        costStatus:
          enum:
          - pending
          - known
          - unknown
          - native
          type: string
        createdAt:
          type: string
        error:
          anyOf:
          - properties:
              code:
                type: string
              message:
                type: string
            required:
            - code
            - message
            type: object
          - type: 'null'
        funding:
          enum:
          - auto
          - hlix
          - organization
          type: string
        id:
          type: string
        projectId:
          type:
          - string
          - 'null'
        providerCostMicros:
          anyOf:
          - format: int64
            maximum: 9007199254740991
            minimum: 0
            type: integer
          - type: 'null'
        reservedMicros:
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        result: {}
        status:
          enum:
          - queued
          - running
          - pending
          - completed
          - failed
          - unknown
          type: string
        toolId:
          type: string
        toolName:
          type: string
        updatedAt:
          type: string
      required:
      - id
      - toolId
      - projectId
      - funding
      - accountingOwner
      - status
      - costStatus
      - reservedMicros
      - providerCostMicros
      - billedMicros
      - result
      - error
      - createdAt
      - updatedAt
      type: object
    SaveToolConnection:
      additionalProperties: false
      properties:
        apiKey:
          maxLength: 10000
          minLength: 1
          type: string
        organizationId:
          maxLength: 40
          pattern: ^\d+$
          type: string
      required:
      - apiKey
      - organizationId
      type: object
    ValidationError:
      properties:
        error:
          properties:
            message:
              type: string
            name:
              type: string
          required:
          - name
          - message
          type: object
        success:
          const: false
          type: boolean
      required:
      - success
      - error
      type: object
    ToolCallInput:
      additionalProperties: false
      properties:
        funding:
          default: auto
          enum:
          - auto
          - hlix
          - organization
          type: string
        idempotencyKey:
          maxLength: 200
          minLength: 1
          type: string
        input:
          additionalProperties: {}
          propertyNames:
            type: string
          type: object
        maxCostMicros:
          description: Provider reservation budget in USD micros. Actual settlement may exceed this amount.
          format: int64
          maximum: 9007199254740991
          minimum: 0
          type: integer
        projectId:
          minLength: 1
          type: string
      required:
      - input
      - idempotencyKey
      type: object
    ToolCallList:
      properties:
        calls:
          items:
            properties:
              accountingOwner:
                enum:
                - router
                - ai
                - web
                - external
                type: string
              billedMicros:
                anyOf:
                - format: int64
                  maximum: 9007199254740991
                  minimum: 0
                  type: integer
                - type: 'null'
              costStatus:
                enum:
                - pending
                - known
                - unknown
                - native
                type: string
              createdAt:
                type: string
              error:
                anyOf:
                - properties:
                    code:
                      type: string
                    message:
                      type: string
                  required:
                  - code
                  - message
                  type: object
                - type: 'null'
              funding:
                enum:
                - auto
                - hlix
                - organization
                type: string
              id:
                type: string
              projectId:
                type:
                - string
                - 'null'
              providerCostMicros:
                anyOf:
                - format: int64
                  maximum: 9007199254740991
                  minimum: 0
                  type: integer
                - type: 'null'
              reservedMicros:
                format: int64
                maximum: 9007199254740991
                minimum: 0
                type: integer
              result: {}
              status:
                enum:
                - queued
                - running
                - pending
                - completed
                - failed
                - unknown
                type: string
              toolId:
                type: string
              toolName:
                type: string
              updatedAt:
                type: string
            required:
            - id
            - toolId
            - projectId
            - funding
            - accountingOwner
            - status
            - costStatus
            - reservedMicros
            - providerCostMicros
            - billedMicros
            - result
            - error
            - createdAt
            - updatedAt
            type: object
          type: array
        nextCursor:
          type:
          - string
          - 'null'
      required:
      - calls
      - nextCursor
      type: object
  parameters:
    OrganizationId:
      description: The workspace (organization) to act in. Omitted, the session's active organization is used.
      in: header
      name: X-Organization-Id
      required: false
      schema:
        type: string
      example: YOUR_WORKSPACE_ID
  securitySchemes:
    apiKey:
      description: An API key issued through `/v1/api/auth/api-key/*`. Browser clients can use their session cookie instead.
      in: header
      name: x-api-key
      type: apiKey
    sessionCookie:
      description: The complete session Cookie header issued by sign-in at the selected API host. Cookie names vary by hosting region and environment; preserve the issued name and value. Browsers send these HTTP-only cookies automatically. Session-only operations require this user session and do not accept an API key.
      in: header
      name: Cookie
      type: apiKey