# Shonin

> Open source, human-in-the-loop approval API for AI agents and automations. One API call emails an approver Approve and Reject buttons; your code polls for the decision or receives a webhook. MIT licensed and self-hostable.

The API base URL is https://shonin.dev/api/v1 and every request needs an Authorization: Bearer API key. The hosted app at https://shonin.dev is a capped demo for trying Shonin out; for real use, self-host it.

## Docs

- [Overview](https://shonin.dev/docs/overview.md): What Shonin is and where the API lives.
- [Quickstart](https://shonin.dev/docs/quickstart.md): Send your first approval request and read the result in three steps.
- [Authentication](https://shonin.dev/docs/authentication.md): How to authenticate requests with your API key.
- [Create Approval](https://shonin.dev/docs/create-approval.md): Create an approval request and email the approver Approve and Reject buttons.
- [Get Approval](https://shonin.dev/docs/get-approval.md): Read the current state of an approval, for polling.
- [Risk Levels](https://shonin.dev/docs/risk-levels.md): How command types map to the risk banner shown in the approval email.
- [Create Decision](https://shonin.dev/docs/create-decision.md): Ask a multiple-choice question instead of a yes or no.
- [Get Decision](https://shonin.dev/docs/get-decision.md): Read the current state of a decision and the option that was chosen.
- [Webhooks](https://shonin.dev/docs/webhooks.md): The JSON payloads Shonin sends when a decision is recorded, and the rules for webhook URLs.
- [How Decisions Work](https://shonin.dev/docs/how-decisions-work.md): How approval links work and why the requesting code cannot approve its own request.
- [Errors](https://shonin.dev/docs/errors.md): Error responses and status codes, including the limits that only apply to the hosted demo.
- [Self-Hosting](https://shonin.dev/docs/self-hosting.md): Run your own copy of Shonin on Next.js, Supabase and Resend.

## Source

- [GitHub repository](https://github.com/Calm-Rock/shonin): source code, MIT license, and the self-hosting guide in the README
- [README as markdown](https://raw.githubusercontent.com/Calm-Rock/shonin/main/README.md): setup and API summary

## Optional

- [All docs in one file](https://shonin.dev/llms-full.txt)