> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrip.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Start with the plan page, https://docs.scrip.dev/agents.md. It covers connecting, configuring, integrating, verifying, and operating a Scrip program.
> Events are asynchronous. `POST /v1/events` returns 202 when the event is accepted. Rules run afterward, so wait for the `event.completed` webhook or poll `GET /v1/events/{id}` before you read balances.
> Send the participant's `external_id` with an event. The first event for a new `external_id` enrolls the participant, so do not create participants first.
> The hosted MCP server is https://mcp.scrip.dev/mcp. It uses OAuth and is read-only. Make changes through the REST API or the dashboard.
> Add `.md` to any docs URL to get the page as Markdown. Request and response schemas are in https://docs.scrip.dev/openapi.json.

# Agents

> The plan an AI agent follows to connect to Scrip, configure a program, integrate the REST API, and verify the result

This page is the plan for an AI agent working on a Scrip integration. Read it first. It is also available as Markdown at `https://docs.scrip.dev/agents.md`.

## Connect

Add the hosted MCP server at `https://mcp.scrip.dev/mcp`. Your client opens Scrip sign-in and stores an OAuth token after you approve access. The server does not accept API keys. See [Connect a client](/mcp/connect).

The hosted server is read-only. Anything that changes data goes through the dashboard or the REST API at `https://api.scrip.dev/v1`, with an API key kept on your server. See [Authentication](/authentication).

## Orient

Call `scrip_get_program_overview`. It returns the programs, assets, rule sets, rules, and tiers the connection can see. Read [Which endpoints you need](/which-endpoints-you-need) before you plan anything. It lists the few calls an app makes as users earn and redeem.

## Configure

Change rules in this order:

1. Read the live configuration with `scrip_get_rule_configuration`.
2. Check the draft with `scrip_lint_rule_configuration`.
3. Build a preview with `scrip_plan_rule_configuration`. It returns the diff, warnings, and final rule order.
4. Simulate the draft with `POST /v1/programs/{programId}/rule-configuration/simulations`. Nothing in the live program changes.
5. Show the preview to a person. Apply it with `POST /v1/programs/{programId}/rule-configuration/apply` only after that person approves.

See [Managing rule configuration](/guides/managing-rule-configuration) and [Testing](/guides/testing).

## Integrate

Your app sends `POST /v1/events` for each user action your rules care about. Give each event an `idempotency_key` built from your own data, such as an order ID. The first event for a new `external_id` enrolls the participant, so you do not create participants first.

Events are asynchronous. `POST /v1/events` returns `202` when Scrip accepts the event. Rules run afterward. Wait for the `event.completed` webhook, or poll `GET /v1/events/{id}`. See [Event processing](/guides/event-processing).

## Verify

Fetch the event with `GET /v1/events/{id}` and read its status and `rule_evaluations`. Then read the participant's balances and history. `scrip_explain_event` gives the same trace through MCP.

When a call fails, match on the error `code` and look it up in [Errors](/errors). Quote the `request_id` when you ask for help.

## Operate

Use `scrip_get_participant_context` and `scrip_get_group_context` to explain a balance. Use `scrip_get_rule_configuration_history` to see which revision was live at a given time and to preview a rollback. Use `scrip_get_program_analytics` for activity, liability, and expiration.

Check [Limits and durations](/limits) before you batch or retry, and keep your client behind the published rate-limit guidance.

## Next steps

<CardGroup cols={2}>
  <Card icon="plug" href="/mcp/tools" title="MCP tools">
    Every tool the server exposes and what each one does.
  </Card>

  <Card icon="book" href="/ai-resources" title="AI resources">
    The context files and guides to load for each kind of task.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.