> ## Documentation Index
> Fetch the complete documentation index at: https://docs.virtuous.org/llms.txt
> Use this file to discover all available pages before exploring further.
# API Playground
> The interactive endpoint pages in the docs — send real requests to CRM+, Raise, and Volunteer endpoints, see real responses, and copy the generated code into your project in your language of choice
The Virtuous API Docs include an **interactive API Playground** — every endpoint page lets you send real requests to the API, see real responses, and copy the resulting code into your project. Instead of reading a static reference page and then guessing how the request actually looks, you compose the request in the browser, fire it, and see exactly what happens.
For partners building integrations, this is one of the most useful features in the docs: it collapses the gap between reading reference material and writing the actual code.
## What the Playground does
When you open an endpoint page (e.g., a specific CRM+ Contact endpoint or a Volunteer Users endpoint), the page includes:
| Element | Purpose |
| -------------------------- | ----------------------------------------------------------------------------------- |
| **Endpoint header** | The HTTP method (GET, POST, PUT, DELETE), the path, and a brief description |
| **Parameter inputs** | Form fields for every path, query, header, and body parameter |
| **Authentication input** | Where you add your Bearer token or OAuth credentials for testing |
| **Send button** | Fires the request against the real API |
| **Response viewer** | Shows the actual HTTP status, headers, and body returned |
| **Generated code samples** | Auto-generated request code in your language of choice — copyable into your project |
Together, these turn each endpoint page into a tiny working API client.
## When to use the Playground
The Playground is most useful in these scenarios:
| Scenario | Why the Playground helps |
| --------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Verifying the request shape before coding** | Build the request in the form; see what works; then translate to code |
| **Exploring an unfamiliar endpoint** | Try different parameters and see what fields the response actually returns |
| **Debugging an integration** | Reproduce the request your code makes; see what the API responds with |
| **Generating boilerplate code** | The code samples handle headers, auth, JSON shape — copy as a starting point |
| **Checking error responses** | Intentionally send a bad request to see the error shape |
| **Confirming spec accuracy** | When the docs reference an audit-flagged spec quirk, test live to see actual behavior |
It's not a substitute for writing production code, but it's the fastest way to **establish what works** before you commit to an implementation.
## Authentication in the Playground
Most Virtuous endpoints require authentication. The Playground supports this directly — you provide a token, the Playground includes it in the request, and you get a real authenticated response.
### Where to put your credentials
The Playground exposes the authentication fields the endpoint requires. For Virtuous:
| API | Auth method | Where in the Playground |
| ------------- | ------------------------ | -------------------------------------- |
| **CRM+** | OAuth 2.0 (Bearer token) | Authorization input — paste your token |
| **Raise** | OAuth 2.0 (Bearer token) | Authorization input — paste your token |
| **Volunteer** | Bearer JWT | Authorization input — paste your token |
For details on getting tokens for each product, see:
* [CRM+ Authentication](/crm/authentication)
* [Raise Authentication](/raise/authentication)
* [Volunteer Authentication](/volunteer/authentication)
### Use sandbox tokens, not production tokens
**Use sandbox or test credentials in the Playground**. The Playground sends real requests to the API — if you use production credentials, you'll affect production data. For exploration, debugging, and learning, sandbox credentials are the right tool. If you're a partner in the [Integration Pathway](/virtuous/partners/integration-pathway), you've been provisioned a sandbox specifically for this.
### Where your credentials are stored
When you paste a token into the Playground:
| Storage | Detail |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **The token is stored in your browser** | So you don't have to re-paste it for every request |
| **The token is sent in the request** | Standard `Authorization: Bearer ` header (or whatever the endpoint requires) |
| **Your credentials aren't sent anywhere else** | The Playground forwards your request to the API directly (or via a proxy when configured) — no third party sees the credentials |
Despite the storage convenience, treat the Playground like any other tool that handles your credentials — don't paste tokens for accounts you don't own, and clear stored tokens when you're done.
## Filling out parameters
Each endpoint's Playground page shows every parameter the endpoint accepts. The form is organized by parameter location:
| Parameter type | Where it appears in the request |
| --------------------- | ----------------------------------------------------- |
| **Path parameters** | In the URL path (e.g., `/users/{id}`) |
| **Query parameters** | After the `?` in the URL (e.g., `?updated_after=...`) |
| **Header parameters** | In HTTP headers |
| **Body parameters** | In the request body (for POST, PUT, PATCH) |
For each parameter, the form shows:
* The parameter name
* The expected type (string, integer, array, etc.)
* Whether it's required or optional
* A description of what it does
* Validation hints (allowed values, format expectations)
### Prefilled examples
When the OpenAPI spec includes example values, the Playground typically prefills the form with those examples. This means for many endpoints, you can hit **Send** immediately with no edits and see a working response. From there, modify parameters to explore different cases.
### Required vs. optional parameters
The Playground may show only required parameters by default, with optional parameters available behind a "Show optional" toggle. This keeps the form focused for quick exploration; expand it when you need to test edge cases.
## Sending requests and reading responses
Once your parameters are filled in:
1. **Click Send** to fire the request
2. **Wait for the response** (typically a few hundred milliseconds for simple GETs; longer for complex queries)
3. **Review the response**:
* HTTP status code (200, 201, 400, 401, 404, 422, 429, 500, etc.)
* Response headers
* Response body (usually JSON)
The response viewer formats JSON cleanly so you can read the actual field shape, nesting, and types — useful when the docs describe a resource and you want to see exactly what it looks like in practice.
### Different response types
| Response type | How it renders |
| ---------------- | -------------------------------------------------------- |
| JSON | Formatted, syntax-highlighted, expandable |
| Plain text | Code block |
| Images | Rendered inline |
| Audio | Audio player |
| Video | Video player |
| Errors (4xx/5xx) | The error body, formatted; status code prominently shown |
For most Virtuous endpoints, the response will be JSON.
## Generated code samples
Beneath each Playground request is **generated code** that recreates the request you just configured. The code is generated based on the parameters you've filled in — change a parameter, and the code updates.
### Available languages
The code samples are typically available in:
* **cURL** — the universal command-line option
* **JavaScript** — for Node.js or browser code
* **Python** — for Python integrations
* **Go**, **Ruby**, **PHP**, **Java**, **C#**, and others (depending on configuration)
You can switch languages to see your request in whatever your team writes in.
### Using the generated code
The generated code is a starting point, not production code. A typical workflow:
1. Configure the request in the Playground
2. Send it; verify it works
3. Copy the generated code in your preferred language
4. Paste it into your integration as a reference
5. Adapt it to your code style, error handling, and authentication management
### What the generated code does well
| Thing | Detail |
| -------------------------- | ---------------------------------------------------- |
| **Correct headers** | Authorization, Content-Type, Accept — set correctly |
| **Correct URL** | Base URL plus path plus query parameters |
| **Correct body shape** | JSON formatted as the API expects |
| **Working starting point** | Should produce the same response if you run it as-is |
### What the generated code doesn't handle
| Thing | What to add in your code |
| ------------------------------------ | -------------------------------------------------------------------------- |
| **Error handling** | The code shows the happy path; you need to handle 4xx and 5xx responses |
| **Retry logic** | See [Error Recovery Patterns](/crm/best-practices/error-recovery-patterns) |
| **Rate limit awareness** | See the Rate Limits page for each product |
| **Pagination** | The code makes one request; for paginated endpoints, you'll need to loop |
| **Production credential management** | Don't hardcode tokens; use proper secret management |
| **Idempotency / retry safety** | See the Idempotency pages where they apply |
Treat generated code as a starting scaffold. The actual production-grade integration patterns are in the Recipes and Best Practices pages.
## Working with the OpenAPI specs
The Playground is generated from the OpenAPI specifications published with the docs. This means:
| What you see in the Playground | Where it comes from |
| ------------------------------------------- | ------------------------------------------- |
| The list of available endpoints | The OpenAPI `paths` definitions |
| Each endpoint's parameters | The OpenAPI `parameters` and `requestBody` |
| Validation hints (required, types, formats) | The OpenAPI schema definitions |
| Example values for prefilling | The OpenAPI `examples` and `example` fields |
| Response shapes | The OpenAPI response schemas |
When you want to see the full OpenAPI spec for a product, the [AI Assistant](/virtuous/docs-guide/ai-assistant) can read it directly. You can also access the spec for direct inspection through the docs site's OpenAPI integration.
### Audit-flagged spec quirks
A reality worth knowing: the OpenAPI specs have some documented quirks (see audit findings referenced throughout the Concepts and Workflow pages). When the Playground shows spec-based information that differs from observed live behavior, the docs' inline annotations call this out.
When in doubt, **trust the live response over the spec description**. The Playground shows you the real API behavior; the spec is the documented expectation.
## Practical workflows
A few patterns that emerge naturally when using the Playground.
### "I'm starting on a new endpoint"
1. Navigate to the endpoint page in the docs
2. Read the description and required parameters
3. Paste in a sandbox token
4. Click **Send** with default (or example) parameters
5. Examine the response
6. Iterate — change parameters, observe what changes
### "I'm writing code for this endpoint"
1. Navigate to the endpoint page
2. Configure the request with realistic parameters
3. Send; verify the response is what you expect
4. Switch the code sample to your language
5. Copy the code
6. Paste into your integration and add proper error handling, retry logic, pagination
### "I'm debugging a failing API call"
1. Get the request your code is making (URL, headers, body)
2. Reproduce the request in the Playground
3. Send it
4. Compare:
* If the Playground succeeds where your code fails → the issue is in your code (auth, header construction, JSON shape)
* If the Playground also fails → the issue is in the request itself (wrong field, wrong endpoint, bad data)
5. Iterate until the Playground succeeds; then update your code to match
### "I'm verifying a documented behavior"
1. Read the docs page describing the behavior
2. Construct the request the docs describe in the Playground
3. Send and observe — does the response match the documented behavior?
4. If yes, great. If no, the spec or the docs may have a known quirk (see audit annotations)
### "I'm exploring an unfamiliar resource"
1. Navigate to the GET (list) endpoint for the resource
2. Send with default parameters
3. Examine the response — what fields exist on each item?
4. Navigate to the GET (detail) endpoint
5. Send for a specific item; see the fuller shape
This is often faster than reading the Concepts page when you want to see actual field shapes.
## Playground limitations
A few things the Playground can't do, by design:
| Limitation | Reason |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Doesn't store request history across sessions | Browser-only state |
| Doesn't paginate automatically | One request per Send click |
| Doesn't handle multi-step workflows | Test each step individually; combine in your code |
| Doesn't simulate webhooks | Webhooks come **from** the API to your endpoint; the Playground is for outbound requests |
| Doesn't simulate OAuth flows beyond the token step | If your workflow needs to construct OAuth flows from scratch, do it in your tooling |
| Doesn't enforce rate limits | You can hammer endpoints from the Playground if you click rapidly — be mindful with sandbox limits |
| Doesn't show usage metrics | For your customer's usage data, query the API directly |
For workflows the Playground doesn't cover, the docs' Workflows, Recipes, and Best Practices groups are your reference.
## Sharing a Playground state
Sometimes you want to share a specific Playground configuration with a teammate — "look at what this endpoint does." A few patterns:
| Approach | How |
| --------------------------------- | ----------------------------------------------------------------------------------- |
| **Share the page URL** | The endpoint page URL works for anyone who can authenticate themselves |
| **Share a screenshot** | Capture the configured form + response for a visual walkthrough |
| **Share the generated code** | Copy the cURL or JavaScript sample and send it; your teammate can run it themselves |
| **Share via Slack with the link** | A link to the endpoint page; your teammate configures it in their browser |
For deeper context, pair the Playground reference with a link to the relevant Workflow or Recipe page.
## Tips for getting the most out of the Playground
A few practices that consistently help:
| Tip | Why |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Always use sandbox credentials** | Production data is real; sandboxes are for exploration |
| **Start with prefilled examples** | If the spec includes them, they're the fastest way to a working request |
| **Switch languages before copying** | Your team's language is more useful than cURL for actual integration code |
| **Verify responses match docs** | When they diverge, trust the response; surface the discrepancy to your Partner Manager |
| **Use the Playground to learn unfamiliar endpoints** | Faster than reading reference material cold |
| **Pair with the AI Assistant** | "Test this request, then ask the assistant to explain the response" — explore + understand in one flow |
## Where to go next
Ask the in-docs AI to explain endpoint responses or generate more sophisticated code.
Send the current endpoint page to your external AI tool for further exploration.
Let your external AI tools query the docs (including OpenAPI specs) while you build.
The full orientation to the docs structure.