# Build on Rippling with AI tools

> Point Cursor, Claude Code, Codex, or a chat assistant at current Rippling docs and make a first Rippling API call.

Install the Rippling rules in your project, paste the prompt on this page, and then make a List companies call with an API token. The prompt sends the assistant to the docs index, tells it when to use an API token or OAuth, and keeps the token in `RIPPLING_API_TOKEN`.

## Before you call the API

You need a Rippling account that can create API tokens.

1.  Navigate to **Developer > API credentials**.
2.  Click **New API token**.
3.  Select the `companies.read` scope.
4.  Click **Create** and copy the token. Rippling shows the token once.

Store the token outside the chat. Full token steps are in [Quickstart: Your first API call](https://developer.rippling.com/documentation/rest-api/essentials/quickstart).

## Paste this prompt

Paste this prompt into the coding agent or chat assistant before you ask it to build against Rippling:

```text
You are helping me build on the Rippling platform.

Source of truth: use the Rippling docs index at https://developer.rippling.com/llms.txt. If the docs and your training data disagree, follow the docs.

For REST API work, start from https://developer.rippling.com/documentation/rest-api/essentials/llms.txt.

Open the index, pick the page whose description matches the task, and fetch that page. Add .md to the page URL (for example https://developer.rippling.com/documentation/rest-api/essentials/quickstart.md). You can also send Accept: text/markdown.

Copy endpoint paths, scopes, and field names from the fetched page. Do not invent them.

New REST calls use https://rest.ripplingapis.com. Do not start a new integration on https://api.rippling.com unless the docs say the resource exists only there.

Never hardcode API tokens or secrets. Read them from the RIPPLING_API_TOKEN environment variable.

A script or integration for my own company uses an API token. An app other companies install from the App Shop uses OAuth. Do not ask those companies for an API token.

Never paste https://developer.rippling.com/llms-full.txt into a chat. That file is every public page in one file. Fetch the single page that matches the task.
```

Fetch one page as Markdown with either the `.md` URL or the `Accept` header:

```bash
curl -sL -H "Accept: text/markdown" \
  "https://developer.rippling.com/documentation/rest-api/essentials/quickstart"
```

## Install Rippling rules

Install the rules once per project so later sessions keep the same docs and auth behavior. Cursor saves a rule file. Claude Code and Codex append a markdown block.

The rules are published at [https://developer.rippling.com/ai/rippling-rules.md](https://developer.rippling.com/ai/rippling-rules) and, for Cursor, [https://developer.rippling.com/ai/rippling.mdc](https://developer.rippling.com/ai/rippling.mdc):

```markdown
# Rippling

- Treat https://developer.rippling.com/llms.txt as the docs source of truth. If the docs and training data disagree, follow the docs.
- For REST API work, start from https://developer.rippling.com/documentation/rest-api/essentials/llms.txt.
- Open the index, pick the page whose description matches the task, and fetch that page's Markdown by adding `.md` to its URL. You can also request the page with `Accept: text/markdown`.
- Copy endpoint paths, scopes, and field names from the fetched page.
- New REST calls use `https://rest.ripplingapis.com`. Do not start a new integration on `https://api.rippling.com` unless the docs say the resource exists only there.
- Never hardcode API tokens. Read them from the `RIPPLING_API_TOKEN` environment variable.
- A script for your own company uses an API token. An app other companies install from the App Shop uses OAuth. Do not ask those companies for an API token.
- Never paste `llms-full.txt` into a chat. Fetch the single page that matches the task.
```

### Install the rules in Cursor

From the project root, write the Cursor rule. The command overwrites `.cursor/rules/rippling.mdc` if you run it again.

```bash
mkdir -p .cursor/rules && curl -fsSL https://developer.rippling.com/ai/rippling.mdc -o .cursor/rules/rippling.mdc
```

Open a chat or agent and [Paste this prompt](https://developer.rippling.com/documentation/rippling-platform/build-with-ai#paste-this-prompt).

### Install the rules in Claude Code

From the project root, append the rules to `CLAUDE.md`. Run the command once. Running it again duplicates the Rippling rules in `CLAUDE.md`.

```bash
curl -fsSL https://developer.rippling.com/ai/rippling-rules.md >> CLAUDE.md
```

Start a session and [Paste this prompt](https://developer.rippling.com/documentation/rippling-platform/build-with-ai#paste-this-prompt).

### Install the rules in Codex

From the project root, append the rules to `AGENTS.md`. Run the command once. Running it again duplicates the Rippling rules in `AGENTS.md`.

```bash
curl -fsSL https://developer.rippling.com/ai/rippling-rules.md >> AGENTS.md
```

Start a session and [Paste this prompt](https://developer.rippling.com/documentation/rippling-platform/build-with-ai#paste-this-prompt).

### Use a chat assistant

Use this path with ChatGPT, Claude, or Gemini.

1.  Paste `https://developer.rippling.com/llms.txt` so the assistant can open the docs index.
2.  For a single page, paste that page's `.md` URL. Add `.md` to the public page URL.
3.  [Paste this prompt](https://developer.rippling.com/documentation/rippling-platform/build-with-ai#paste-this-prompt), then ask your question.

An assistant without web browsing cannot open these URLs. Paste the page's Markdown into the chat.

## Use an API token or OAuth

Pick one auth method before you write the integration.

-   **API token.** Use an API token for a script or integration that runs for your own company. Create a Bearer token in Rippling. The token can access the intersection of the creator's permission profile and the scopes you select on the token. Start with [Quickstart: Your first API call](https://developer.rippling.com/documentation/rest-api/essentials/quickstart) and [API tokens and permissions](https://developer.rippling.com/documentation/rest-api/essentials/api-tokens).
-   **OAuth for an App Shop app.** Use OAuth when other companies install your app from the App Shop. Rippling is the authorization server. Rippling sends the person installing your app to your redirect URL with a `code` parameter, and your app exchanges that code for access and refresh tokens. Follow [Installation (OAuth)](https://developer.rippling.com/documentation/developer-portal/v2-guides/installation). The client ID and client secret are on the app listing. See [OAuth credentials](https://developer.rippling.com/documentation/developer-portal/v2-guides/oauth).

Call the [Rippling REST API](https://developer.rippling.com/documentation/rest-api) after you pick the auth method.

## Make your first API call

Use an API token for this call. `YOUR_API_TOKEN` is the token you copied from **Developer > API credentials**.

```bash
export RIPPLING_API_TOKEN="YOUR_API_TOKEN"

curl -X GET 'https://rest.ripplingapis.com/companies/' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $RIPPLING_API_TOKEN"
```

A successful List companies response includes a `results` array with your company:

```json
{
  "results": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Acme Corporation",
      "legal_name": "Acme Corporation Inc."
    }
  ]
}
```

Field details are in [Quickstart: Your first API call](https://developer.rippling.com/documentation/rest-api/essentials/quickstart).

## Check that the assistant used current docs

Ask your AI tool:

> How do I authenticate my first Rippling API call?

A correct answer names all of the following:

-   Base URL `https://rest.ripplingapis.com`
-   Header `Authorization: Bearer` with a token read from an environment variable (for example `RIPPLING_API_TOKEN`)
-   `GET /companies/` with the `companies.read` scope

An answer that uses `https://api.rippling.com` for this call, or that pastes the token into source, did not follow the docs. Compare the answer with [Quickstart: Your first API call](https://developer.rippling.com/documentation/rest-api/essentials/quickstart).

## Fix a 401 or 403

| Error | Cause | Fix |
| --- | --- | --- |
| `401 Unauthorized` with `"message": "Missing or invalid API key"` | The API token is missing, invalid, expired, or revoked. | Send the current token in the `Authorization: Bearer` header. Create a new token if Rippling revoked the old one. |
| `403 Forbidden` | The request is authenticated but missing a scope or a permission on the token owner's profile. The message can include `Insufficient oauth scopes`. | Add the required scope to the token, and confirm the token owner can see that data in Rippling. |

Status codes and example bodies are in [API errors and troubleshooting](https://developer.rippling.com/documentation/rest-api/essentials/troubleshooting).

## Store credentials outside the chat

Store API tokens and OAuth secrets in environment variables or a secrets manager. Keep them out of prompts, chat history, and source control. Grant the narrowest scopes that cover the work, and rotate a credential if it is exposed. Details are in [API tokens and permissions](https://developer.rippling.com/documentation/rest-api/essentials/api-tokens).

## Use the Rippling CLI

The Rippling CLI is optional. Use it when you want a coding agent to run Rippling CLI commands. API calls and the docs rules on this page work without the CLI.

> **Developer Program closed beta:**
> Access to the Rippling CLI is gated behind the **Developer Program**, which is currently in a closed beta.

Apply for access in [Get started with the Developer Program](https://developer.rippling.com/documentation/rippling-platform/developer-program/get-started) before you install the CLI. Install and update steps are in [Get started with the Rippling CLI](https://developer.rippling.com/documentation/rippling-platform/rippling-cli/get-started).

Source: https://developer.rippling.com/documentation/rippling-platform/build-with-ai

> For the complete documentation index, see [llms.txt](https://developer.rippling.com/llms.txt). Public pages have a Markdown version at the same URL with .md added.
