# Botect API

## Documentation

- [Introduction](https://docs.botect.ai/introduction.md): Botect scores every visitor session for bot-likelihood from behavioral, JS, and heuristic signals — then tells your backend whether to allow, challenge, or block, in under 50 ms.
- [Quickstart](https://docs.botect.ai/quickstart.md): Enable scoring on a project, stream signals from the browser, and read your first verdict from your backend.
- [Authentication](https://docs.botect.ai/authentication.md): Botect uses three credentials: an account API token for configuration, a site key for ingest, and a private key for verdict reads.
- [How scoring works](https://docs.botect.ai/how-scoring-works.md): Three independent engines turn a session's signals into a single 1–99 bot-likelihood score, combined by strongest evidence, with stable detection IDs and plain-English reasons.
- [Signals & fields](https://docs.botect.ai/signals.md): The composable signal fields exposed on a scored session — what they mean, their types, and which are usable in custom rules.
- [Score bands](https://docs.botect.ai/score-bands.md): How the 1–99 score maps to bands relative to your project threshold, and how toggles turn bands into allow / challenge / block actions.
- [Rules](https://docs.botect.ai/rules.md): Go beyond toggles with a safe, composable boolean grammar over every signal field — compiled to an AST, never eval'd.
- [Verified bots](https://docs.botect.ai/verified-bots.md): How Botect recognizes legitimate search and AI crawlers and allows them by default — so good bots are never blocked for looking automated.
- [Plans & quotas](https://docs.botect.ai/plans-quotas.md): How Botect meters ingest volume against a monthly quota — and why the data plane is never rate-limited.
- [Errors](https://docs.botect.ai/errors.md): Botect's stable JSON error shape, status codes, and the cases that are deliberately not errors.

## API Reference

- [POST /v1/events](https://docs.botect.ai/endpoints/events.md): Ingest a batch of privacy-safe interaction signals for a session. Authenticated by site key, async-scored, idempotent, never rate-limited.
- [GET /v1/sessions/{session_token}/verdict](https://docs.botect.ai/endpoints/verdict.md): Read the bot-detection decision for a session. Authenticated by private key, Redis-cached, fails open, under 50 ms p99.
- [POST /v1/projects/{project}/scoring](https://docs.botect.ai/endpoints/scoring-enable.md): Enable bot scoring on a project and mint its site key and private key. The private key is returned once.
- [POST /v1/projects/{project}/scoring/rotate](https://docs.botect.ai/endpoints/scoring-rotate.md): Rotate a project's site key or private key. The old key is invalidated immediately and a new one is returned.
- [PUT /v1/projects/{project}/scoring/settings](https://docs.botect.ai/endpoints/scoring-settings.md): Update a project's enforcement toggles and bot threshold. Changes bust the verdict cache so they take effect promptly.
- [GET /v1/projects/{project}/rules](https://docs.botect.ai/endpoints/rules-list.md): List a project's custom bot rules in evaluation order.
- [POST /v1/projects/{project}/rules](https://docs.botect.ai/endpoints/rules-create.md): Create a custom bot rule. The expression is compiled and validated to a safe AST before it's stored.
- [DELETE /v1/projects/{project}/rules/{rule}](https://docs.botect.ai/endpoints/rules-delete.md): Delete a custom bot rule from a project.
- [GET /user](https://docs.botect.ai/endpoints/user.md): Return the authenticated user for an account API token. A quick way to verify a token works.
- [GET /v1/account](https://docs.botect.ai/endpoints/account.md): Return the account an API token acts on, plus the caller's role. Reachable without an active subscription.

## Changelog

- [Release notes](https://docs.botect.ai/changelog.md): What's new in the Botect API — features, behavior changes, and improvements, newest first.