# JavaScript API

> AgentGate.init, execute, render, getResponse, reset and remove, their options and results, and the error codes execute() rejects with.

The SDK defines one global, `window.AgentGate`.

| Member | Purpose |
| --- | --- |
| `init(options)` | start the collectors at page load; set the default site key and endpoint |
| `execute(options)` | verify now; resolves with a token |
| `render(element, options)` | create a widget; returns its id |
| `getResponse(id)` | the widget's current token, or `""` |
| `reset(id)` | return a widget to its first state |
| `remove(id)` | take a widget out of the page |
| `version` | the SDK version, for example `"1.0.0"` |
| `errors` | the list of error codes |
| `Error` | the error class (`AgentGate.Error`) |
| `locales` | the UI languages available |

## init(options)

```js
AgentGate.init({ siteKey: "site_…", endpoint: "https://agentgate.example" });
```

| Option | Meaning |
| --- | --- |
| `siteKey` | default site key for `execute()` and `render()` |
| `endpoint` | the AgentGate origin; defaults to the origin that served the script |

Call it as early as possible: it starts document-wide interaction counters
(key and pointer timings, never what is typed) that the check scores. It may
be called more than once; later calls only change `siteKey` and `endpoint`.
Declarative widgets call it for you.

> [!WARNING]
> `execute()` without an earlier `init()` still works, but the behaviour
> trace is missing. AgentGate labels such verifications
> `agentgate:sdk:late_init` and the built-in rule `sdk_late_init` asks for the
> visible check. Call `init()` at page load.

## execute(options)

Runs a verification and resolves with a token. Use it for requests your code
sends itself.

```js
try {
  const { token, expiresAt, decisionId } = await AgentGate.execute({ action: "signup" });
  await fetch("/api/signup", { method: "POST", headers: { "X-AgentGate-Token": token }, body });
} catch (err) {
  if (err instanceof AgentGate.Error) console.warn(err.code, err.status);
}
```

| Option | Default | Meaning |
| --- | --- | --- |
| `action` | | required; `[a-z0-9_]{1,64}` and configured for the site |
| `siteKey` | the `init()` site key | the site key |
| `endpoint` | the `init()` endpoint | the AgentGate origin |
| `signal` | | an `AbortSignal`; aborting rejects with `aborted` |
| `timeout` | `30000` | milliseconds for the automatic part; rejects with `timeout` |
| `checkTimeout` | `300000` | milliseconds allowed once the visible check is shown (a person is acting) |
| `mode` | `invisible` | reported to the server; `interactive` always asks for the check |
| `container` | a modal dialog | an element to show the check in, if one is needed |
| `lang` | the browser's languages | UI language of the check |

The result:

| Field | Meaning |
| --- | --- |
| `token` | the single-use token to send to your server |
| `expiresAt` | when the token expires, Unix milliseconds (two minutes by default) |
| `decisionId` | the decision's ID, for support and the dashboard |
| `clearance`, `clearanceExpiresAt` | for clearance actions only ([clearances](/docs/tokens-and-clearances#clearances)) |

Call `execute()` just before sending the request, not at page load: the
token is short-lived and single use.

## Errors

`execute()` rejects, and `errorCallback` receives, an `AgentGate.Error` with
a stable `code` (and `status`, the HTTP status, when the server answered):

| Code | Meaning | What to do |
| --- | --- | --- |
| `site_invalid` | unknown or missing site key | check the site key |
| `action_invalid` | the action is malformed or not configured for the site | check `action` and the site's actions |
| `origin_denied` | this page's origin is not allowed for the site key | add the origin to the site |
| `rate_limited` | too many challenges or verifications from this address | retry after `Retry-After` |
| `challenge_failed` | the evidence was declined, or the check was not passed | let the person retry |
| `challenge_expired`, `challenge_used`, `challenge_invalid`, `too_many_attempts` | the challenge cannot be used again | call `execute()` again |
| `schema_unsupported` | SDK and server disagree on the protocol | load the SDK from the same AgentGate |
| `payload_too_large`, `bad_request` | the request was malformed | report it: this is a bug |
| `unavailable` | AgentGate had a dependency failure | retry later |
| `timeout` | `timeout` (or `checkTimeout`) passed | retry |
| `aborted` | your `signal` aborted | none |
| `canceled` | the person closed the check (Escape or Cancel) | none, or offer to retry |
| `network` | the request failed (offline, DNS, CORS, blocked by an extension) | retry; check CSP `connect-src` |
| `error` | anything else | retry; report if it persists |

`AgentGate.errors` lists every code. The server-side meaning of each is on
[Error codes](/docs/error-codes#browser-sdk).

## render(element, options)

Creates a widget in `element` (an element or a CSS selector) and returns its
id. Options and callbacks are on [Widget configuration](/docs/widget-reference#rendering-from-code).
Rendering into an element that already holds a widget replaces it.

## getResponse(id)

The widget's current token, or `""` when it has none (not verified yet,
consumed by a submission, or expired).

## reset(id)

Cancels a verification in progress (without calling `errorCallback`),
clears the token and returns the widget to its first state: the
"Protected" chip, and the Verify button in interactive mode.

## remove(id)

Cancels a verification in progress, then takes back everything the widget
added: its submit handler, the `agentgate_token` field it created (a field
your page provides is kept), its elements, timers and the attributes it set
on the host. The form then submits as if AgentGate had never rendered
there. Call it from your framework's unmount or cleanup hook.

`id` can be the id `render()` returned, the host element, or omitted (the
most recently rendered widget). An id that no longer exists does nothing.