Web providers

Organization web-provider credentials and activation state.

Generated from contract version 1.0.0 — the same document /v1/api/openapi.json 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
PATCH	/v1/api/web-providers/{provider}	Enable or disable a stored web-provider key
DELETE	/v1/api/web-providers/{provider}/key	Remove a stored web-provider key
PUT	/v1/api/web-providers/{provider}/key	Add or replace a web-provider key
GET	/v1/api/web-providers/crawl	Show hlix-crawl usage against the plan allowance
PATCH	/v1/api/web-providers/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 referenceEvery resource in the published contract, and what is deliberately not in it.

API & OpenAPIDownload the contract, generate a client, and read the compatibility policy.

TypeScript SDKAuth, retries, typed errors, uploads and streaming, already built.

CLI referenceThe same operations from a terminal, with a stable JSON envelope.