Source: docs/integration/prompt-integrations.md

Browser prompt integrations

Use a prompt integration when an operator has given you an endpoint, an

origin, an input schema, and a public Turnstile sitekey. This is a frontend

integration only: do not add an API key, prompt, model name, or secret to the

browser code.

Integration bundle

The operator provides an integration bundle containing:

Rendering Turnstile

Render the Turnstile widget using the provided sitekey and action. The

action is mandatory — the server rejects tokens that do not match the

configured action.

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit" defer></script>
<script>
  const widgetId = turnstile.render("#turnstile-container", {
    sitekey: integration.turnstile_sitekey,
    action: integration.turnstile_action,   // required
    callback: (token) => { /* store token */ },
    "expired-callback": () => { /* reset */ },
  });
</script>

The action value is returned in the admin API response when the integration

is created. Hardcoding the action in the browser code is safe — it is not a

secret.

Request

Send the declared form data and the single-use token to the provided endpoint:

const response = await fetch(integration.endpoint, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    input: { business_context: form.businessContext.value },
    turnstile_token: token,
  }),
});

const body = await response.json();
if (!response.ok) throw new Error(body.error?.code ?? "PROMPT_INTEGRATION_FAILED");
renderResult(body.data);

The input object must match the schema returned with the integration

bundle. The response is always JSON and data matches the configured output

schema. Treat both the form values and returned data as untrusted content.

Prompt Integration usage is attributed to the account that owns the integration.

This browser-only route does not accept or require a user_id; do not add one

to the request for billing purposes.

Retry and failure handling

Turnstile tokens are single-use. Reset the widget after every submission,

including failures, before allowing another attempt. Do not retry a

VALIDATION_ERROR, ORIGIN_DENIED, or TURNSTILE_INVALID response without

fixing the request or obtaining a new token. Respect Retry-After for

RATE_LIMITED and DAILY_QUOTA_EXCEEDED. A 404 INTEGRATION_DISABLED means

the operator has disabled the endpoint.

Contract

The public OpenAPI document is the source of truth for the execution route:

api.openapi.yaml. The endpoint is browser-only, accepts no credentials, and

does not provide a server-to-server integration mode.