integrations

integrations.add_endpoints

Add Endpoints to Integration

Effects: write

Add one or more API endpoints to an HTTP-API integration as callable tools, merged additively into the integration for base_url (created if none exists). Each endpoint becomes a tool with params + request/response schemas inferred from the samples you pass. When CREATING a new integration, provide auth: either identity (saved Browser Identity name/id) for cookie-session APIs, OR an auth block for token/header APIs, e.g. {type:'bearer', token:'...'} or {type:'api_key', token:'...', header_name:'X-API-Key'}. Updates keep the existing auth unless a new auth is passed. Returns the new tool count and names. Refresh the tools list afterwards to use them.

Arguments

Argument	Type	Required	Description
auth	object	no	Auth block for a NEW token/header integration (or to change auth on update): {type: none|bearer|api_key|basic|custom_headers, ...}. bearer/basic → {token}; api_key → {token, header_name?}; custom_headers → {headers:{name:value,...}}. Token values are encrypted. Omit for browser_identity (use identity) or to keep existing auth.
base_url	string	yes	API base URL of the integration, e.g. https://api.boomnow.com
const_fields	array	no	Request-body fields that NEVER vary, as dotted paths into the sample body — e.g. ['query', 'operationName'] for a GraphQL endpoint, or ['envelope.version']. Their value is taken from the sample, pinned server-side, and HIDDEN from the model: it can neither see nor mistype them, and only the parts that actually change (variables, ids, dates) stay in the tool's arguments. Use for GraphQL documents, SOAP envelopes, API versions and tenant ids.
endpoints	array	yes	Endpoints to add. Each: {method, path, query?(object), request_body?(object sample), response_body?(object/array sample)}. path is relative to base_url, e.g. /api/conversations/all.
extract	object	no	Explicit browser_identity auth extract for a NEW integration when auto-detect can't find one. One block, e.g. {kind:'cookie', name:'_session', value_format:'raw', header_name:'Cookie', header_template:'{{name}}={{value}}'} — or a LIST of blocks, merged, which is what a session-cookie API needs: the session in Cookie AND a CSRF header echoing one cookie back: {kind:'composite', blocks:[{kind:'cookies', origin:'https://app.example.com'}, {kind:'cookie', name:'xsrf_token', header_name:'x-xsrf-token'}]}. kind 'cookies' sends every live cookie for that origin (the only way to send an HttpOnly session cookie); its origin must cover the integration's base_url host. Updates reuse existing auth, so omit then.
identity	string	no	Saved Browser Identity name or numeric id — one way to auth a NEW cookie-session integration (updates reuse existing auth). For token/header APIs use auth instead.
keepalive_operation	string	no	operationId the session keep-alive should ping to hold a cookie session open, e.g. 'getHomeWidgetAlerts'. Must be a param-less GET on this integration. Set it when the API has no obvious session probe in its names (the sweeper looks for validate/session/me/whoami/health) AND its session idles out in hours: without it such an integration only gets the hourly origin warm and dies overnight. Carried over on later updates; OMIT to leave it unchanged.
name	string	no	Display name when creating a new integration. OMIT to default to the host.

integrations.capture_session

Capture Integration Session

Effects: write

Restore an expired integration session by capturing the LIVE auth of an open browser page — works for COOKIE sessions (browser_identity) AND TOKEN/HEADER sessions (bearer / api_key / custom_headers, e.g. Devise access-token/client/uid). First call browser_open(url, identity_name) for the integration's site (the page must be logged in AND have called its API), then pass that page_id here with integration_id or base_url. For cookie sessions it captures the full storage_state (incl httpOnly cookies page JS can't read) into the bound identity; for token sessions it captures the auth headers the page sends to the API host and binds them. Re-connects the integration. The captured secret never leaves the server (returns counts only). Generic — any site, any auth scheme, no local Playwright.

Arguments

Argument	Type	Required	Description
base_url	string	no	Or the integration's base URL, e.g. https://api.boomnow.com.
integration_id	integer	no	Integration id (from integrations.list).
page_id	string	yes	page_id from a prior browser_open of the integration's site (logged in).

integrations.get_endpoints

Get Integration Endpoints

Effects: read

List every endpoint (operationId, method, path) registered on an HTTP-API integration. Identify it by integration_id or base_url. Use this to review what tools exist before integrations.remove_endpoints or add_endpoints.

Arguments

Argument	Type	Required	Description
base_url	string	no	Or the integration's base URL, e.g. https://api.boomnow.com
integration_id	integer	no	Integration id (from integrations.list).

integrations.list

List Integrations

Effects: read

List the workspace's external integrations (HTTP-API + MCP), each with its id, provider name, base_url, transport, status, and registered tool count. Use before integrations.add_endpoints to find the integration id / base_url.

Arguments

No arguments.

integrations.remove_endpoints

Remove Endpoints from Integration

Effects: write

Remove endpoints (tools) from an HTTP-API integration — e.g. junk paths like static assets, /socket.io, or SPA routes that aren't real API calls. Identify the integration by integration_id or base_url, and the endpoints to drop by operation_ids (e.g. getSocketIo) and/or paths (e.g. /socket.io/). Re-registers the catalog so the removed tools disappear. Returns removed + remaining counts.

Arguments

Argument	Type	Required	Description
base_url	string	no	Or the integration's base URL.
integration_id	integer	no	Integration id (from integrations.list).
operation_ids	array	no	operationIds to remove, e.g. ["getSocketIo","getPieScreensMenu"].
paths	array	no	Exact spec paths to remove (all methods), e.g. ["/socket.io/"].

integrations.set_auth

Set Integration Auth

Effects: write

Set or update the authentication on an HTTP-API integration, generically. Identify it by integration_id or base_url. Pass auth = {type: bearer|api_key|basic|query|custom_headers|browser_identity|none, ...}: bearer/basic → {token}; api_key → {token, header_name?} (key rides in a HEADER); query → {token, param_name} (key rides in the QUERY STRING, e.g. param_name='api_key' → ?api_key=…); custom_headers → {headers:{name:value,...}}; browser_identity → {identity_id|identity_name, extract}. Token values are encrypted; nothing is stored in cleartext. To only refresh a browser_identity session, OMIT auth and pass cookies (and/or local_storage) — they are merged into the bound identity without touching its config. (oauth2 / service_account use the REST settings flow.)

Arguments

Argument	Type	Required	Description
auth	object	no	Auth to set: {type, token?, header_name?, headers?(object), identity_id?, identity_name?, extract?(object)}. Omit to only refresh cookies on an existing browser_identity integration.
base_url	string	no	Or the integration's base URL, e.g. https://api.boomnow.com.
cookies	array	no	Cookies to merge into the bound browser identity. Each {name, value, domain?, path?, expires?}. Existing names are overwritten; new ones added.
integration_id	integer	no	Integration id (from integrations.list).
local_storage	array	no	localStorage entries to merge. Each {origin, name, value}.

integrations.sync_knowledge

Sync Integration Knowledge

Effects: write

Refresh a knowledge collection from an integration's endpoints, for content too large to return in a tool response (a 300KB+ catalogue an agent could never fit in one call). Pass sources + collection to configure and run in one step — they are stored on the integration, so later runs need only integration_id. Every run is a FULL refresh; a source whose rendered text is unchanged is skipped (reported unchanged) rather than re-uploaded. Returns a per-source report: created / updated / unchanged / no_records / error.

Arguments

Argument	Type	Required	Description
collection	string	no	Knowledge collection to publish into, created if absent. Required when sources is given; ignored otherwise.
description	string	no	Description for a newly created collection. Optional.
force	boolean	no	Re-upload and re-index every source even when its rendered text is unchanged. Use after a fix BELOW the text — chunking, extraction, embeddings — which the content digest cannot see (without this the only repair was deleting the synced files by hand).
integration_id	integer	yes	Integration id (from integrations.list) to sync.
sources	array	no	Sources to store on the integration and then sync. OMIT to re-run whatever is already stored. REPLACES the stored list wholesale — pass every source you want, not just a new one, or the omitted ones stop syncing. Each item: {operation_id (from integrations.get_endpoints), arguments? (e.g. {"locale": "ru"}), title?, spec, endpoint?}. endpoint {method, path} lets the sync call an operation NOT registered on the integration (kept off the agent tool surface — e.g. a 300KB catalogue). spec is the projection: {records (REQUIRED dotted path to the row list), envelopes?, recurse?, title?, body?, meta?, drop?, max_chars?}. Same operation with different arguments is a separate document, which is how one endpoint serves four locales.