# Web providers

Organization web-provider credentials and activation state.

Generated from contract version `1.0.0` — the same document [`/v1/api/openapi.json`](/api/openapi/) serves.

## Prerequisites

- An API key in `x-api-key`, or a browser session cookie
- `X-Organization-Id` naming the workspace to act in, unless the session already has an active one
- The base URL for your deployment, `https://server.hlix.ai` by default

## Operations

| Method | Path | Operation |
| --- | --- | --- |
| `GET` | `/v1/api/web-providers` | [List web-provider credential state](#list-web-provider-credential-state) |
| `PATCH` | `/v1/api/web-providers/{provider}` | [Enable or disable a stored web-provider key](#enable-or-disable-a-stored-web-provider-key) |
| `DELETE` | `/v1/api/web-providers/{provider}/key` | [Remove a stored web-provider key](#remove-a-stored-web-provider-key) |
| `PUT` | `/v1/api/web-providers/{provider}/key` | [Add or replace a web-provider key](#add-or-replace-a-web-provider-key) |
| `GET` | `/v1/api/web-providers/crawl` | [Show hlix-crawl usage against the plan allowance](#show-hlix-crawl-usage-against-the-plan-allowance) |
| `PATCH` | `/v1/api/web-providers/crawl` | [Opt the workspace in or out of hlix-crawl](#opt-the-workspace-in-or-out-of-hlix-crawl) |

## List web-provider credential state

`GET /v1/api/web-providers` · operation ID `listWebProviders`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | WebProviderState[] | The provider catalog. Stored secrets are represented only by `hasApiKey`; no key is returned. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Only workspace owners and admins may inspect or change provider credentials. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Enable or disable a stored web-provider key

`PATCH /v1/api/web-providers/{provider}` · operation ID `toggleWebProvider`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `provider` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `ToggleWebProvider` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `enabled` | boolean | **yes** |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | WebProviderState | The safe provider state after the toggle. |
| `400` | ValidationError \| ApiError | The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`). |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Only workspace owners and admins may inspect or change provider credentials. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |
| `409` | ApiError | The key cannot be enabled because none is stored. |

## Remove a stored web-provider key

`DELETE /v1/api/web-providers/{provider}/key` · operation ID `removeWebProviderKey`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `provider` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | WebProviderState | The safe provider state after the key was removed and disabled. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Only workspace owners and admins may inspect or change provider credentials. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Add or replace a web-provider key

`PUT /v1/api/web-providers/{provider}/key` · operation ID `saveWebProviderKey`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `provider` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `SaveWebProviderKey` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `apiKey` | string | **yes** | min length 1, max length 10000 |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | WebProviderState | The safe provider state after saving and enabling the key. |
| `400` | ValidationError \| ApiError | The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`). |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Only workspace owners and admins may inspect or change provider credentials. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Show hlix-crawl usage against the plan allowance

`GET /v1/api/web-providers/crawl` · operation ID `getHlixCrawlStatus`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | HlixCrawlStatus | Month-to-date hlix-crawl usage, the plan allowance and overage rate. `termsSource` is `plan` when the org's billing subscription defines the numbers, `placeholder` while billing has not. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Only workspace owners and admins may inspect or change provider credentials. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Opt the workspace in or out of hlix-crawl

`PATCH /v1/api/web-providers/crawl` · operation ID `toggleHlixCrawl`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `ToggleWebProvider` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `enabled` | boolean | **yes** |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | HlixCrawlStatus | The hlix-crawl status after the toggle. |
| `400` | ValidationError \| ApiError | The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`). |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Only workspace owners and admins may inspect or change provider credentials. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## If a request fails

These apply to every operation on this page.

- `400` — the body failed schema validation, or the request named no active organization. A `ValidationError` body carries the failing fields; an `ApiError` body carries only `error`.
- `401` — no valid session or API key.
- `403` — authenticated, but not a member of the named organization, or a client collaborator without the required access.
- `404` — no such resource **in this workspace**. Absent and not-visible are deliberately the same answer; do not infer cross-tenant existence from it.
- `409` — the expected revision or state is stale, or another operation currently owns the transition.
- `500` — the operation failed server-side. Retry only where an idempotency key makes that safe.

## Next steps

[API reference](/api/reference/)
  [API & OpenAPI](/api/openapi/)
  [TypeScript SDK](/sdk/typescript/)
  [CLI reference](/reference/cli/)