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.
- Navigate to Developer > API credentials.
- Click New API token.
- Select the
companies.readscope. - 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.
Paste this prompt
Paste this prompt into the coding agent or chat assistant before you ask it to build against Rippling:
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:
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 and, for Cursor, https://developer.rippling.com/ai/rippling.mdc:
# 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.
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.
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.
curl -fsSL https://developer.rippling.com/ai/rippling-rules.md >> CLAUDE.md
Start a session and 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.
curl -fsSL https://developer.rippling.com/ai/rippling-rules.md >> AGENTS.md
Start a session and Paste this prompt.
Use a chat assistant
Use this path with ChatGPT, Claude, or Gemini.
- Paste
https://developer.rippling.com/llms.txtso the assistant can open the docs index. - For a single page, paste that page's
.mdURL. Add.mdto the public page URL. - 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 and API tokens and permissions.
- 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
codeparameter, and your app exchanges that code for access and refresh tokens. Follow Installation (OAuth). The client ID and client secret are on the app listing. See OAuth credentials.
Call the Rippling 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.
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:
{
"results": [
{
"id": "507f1f77bcf86cd799439011",
"name": "Acme Corporation",
"legal_name": "Acme Corporation Inc."
}
]
}
Field details are in Quickstart: Your first API call.
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: Bearerwith a token read from an environment variable (for exampleRIPPLING_API_TOKEN) GET /companies/with thecompanies.readscope
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.
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.
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.
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.
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 before you install the CLI. Install and update steps are in Get started with the Rippling CLI.