Hlix Web Providers 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 Web Providers API
  version: 1.0.0
servers:
- url: https://server.hlix.ai
  description: API server
security:
- apiKey: []
- sessionCookie: []
tags:
- description: Organization web-provider credentials and activation state.
  name: web-providers
paths:
  /v1/api/web-providers:
    get:
      operationId: listWebProviders
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/WebProviderState'
                type: array
          description: The provider catalog. Stored secrets are represented only by `hasApiKey`; no key is returned.
        '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: Only workspace owners and admins may inspect or change provider credentials.
        '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 web-provider credential state
      tags:
      - web-providers
  /v1/api/web-providers/crawl:
    get:
      operationId: getHlixCrawlStatus
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HlixCrawlStatus'
          description: 'Month-to-date hlix-crawl usage, plan allowance and overage rate. `termsSource: plan` identifies subscription-defined terms; `termsSource: placeholder` identifies provisional terms not supplied by billing.'
        '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: Only workspace owners and admins may inspect or change provider credentials.
        '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: Show hlix-crawl usage against the plan allowance
      tags:
      - web-providers
    patch:
      operationId: toggleHlixCrawl
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToggleWebProvider'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HlixCrawlStatus'
          description: The hlix-crawl status after the toggle.
        '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: Only workspace owners and admins may inspect or change provider credentials.
        '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: Opt the workspace in or out of hlix-crawl
      tags:
      - web-providers
  /v1/api/web-providers/{provider}:
    patch:
      operationId: toggleWebProvider
      parameters:
      - in: path
        name: provider
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToggleWebProvider'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebProviderState'
          description: The safe provider state after the toggle.
        '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: Only workspace owners and admins may inspect or change provider credentials.
        '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.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The key cannot be enabled because none is stored.
      summary: Enable or disable a stored web-provider key
      tags:
      - web-providers
  /v1/api/web-providers/{provider}/key:
    delete:
      operationId: removeWebProviderKey
      parameters:
      - in: path
        name: provider
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebProviderState'
          description: The safe provider state after the key was removed and disabled.
        '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: Only workspace owners and admins may inspect or change provider credentials.
        '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 stored web-provider key
      tags:
      - web-providers
    put:
      operationId: saveWebProviderKey
      parameters:
      - in: path
        name: provider
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveWebProviderKey'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebProviderState'
          description: The safe provider state after saving and enabling the key.
        '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: Only workspace owners and admins may inspect or change provider credentials.
        '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: Add or replace a web-provider key
      tags:
      - web-providers
components:
  schemas:
    ApiError:
      additionalProperties: {}
      properties:
        error:
          type: string
      required:
      - error
      type: object
    HlixCrawlStatus:
      properties:
        allowance:
          maximum: 9007199254740991
          minimum: 0
          type: integer
        enabled:
          type: boolean
        overagePer100:
          minimum: 0
          type: number
        platformAvailable:
          type: boolean
        termsSource:
          enum:
          - plan
          - placeholder
          type: string
        unavailableReason:
          type:
          - string
          - 'null'
        usedThisMonth:
          minimum: 0
          type: number
      required:
      - enabled
      - platformAvailable
      - unavailableReason
      - usedThisMonth
      - allowance
      - overagePer100
      - termsSource
      type: object
    WebProviderState:
      properties:
        capabilities:
          items:
            enum:
            - search
            - read
            type: string
          type: array
        credentialSource:
          enum:
          - organization
          - hlix
          type: string
        description:
          type: string
        enabled:
          type: boolean
        hasApiKey:
          type: boolean
        label:
          type: string
        platformAvailable:
          type: boolean
        provider:
          enum:
          - jina
          - firecrawl
          type: string
      required:
      - provider
      - label
      - description
      - capabilities
      - hasApiKey
      - enabled
      - credentialSource
      - platformAvailable
      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
    ToggleWebProvider:
      additionalProperties: false
      properties:
        enabled:
          type: boolean
      required:
      - enabled
      type: object
    SaveWebProviderKey:
      additionalProperties: false
      properties:
        apiKey:
          maxLength: 10000
          minLength: 1
          type: string
      required:
      - apiKey
      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