API Playground

The API Playground lets you call the RevKeen API directly from this documentation site using your own API key.

It's powered by:

• Scalar for the interactive API console
• Unkey for secure API keys (x-revkeen-key)
• The same OpenAPI spec that drives our SDKs and Engine API

1. Before You Start

1.1 Get your Sandbox API key

1. Sign in to the RevKeen Dashboard
2. Go to Developers → API Keys
3. Create a new key with:
   • Environment: Sandbox
   • Prefix: rk_sandbox_...
4. Copy the key and keep it secret – it has full access to your Sandbox data.

2. Using the Playground (Try the API)

The Playground is integrated into the API Reference via Scalar's Try-it console.

2.1 Calling your first endpoint

1. Open the API Reference.
2. In the sidebar, select GET /customers.
3. On the right-hand side, locate the "Try it" panel.
4. In the environment/server selector, choose:
   • Sandbox → https://sandbox-api.revkeen.com/v1
5. In the Headers section, add:
   • x-revkeen-key: rk_sandbox_...
6. Click Send.

You should receive a response similar to:

{
  "page": 1,
  "limit": 20,
  "total": 0,
  "has_more": false,
  "data": []
}

3. Common Playground Scenarios

Below are some safe, high-signal flows you can test directly from the docs. For all examples, use the Sandbox environment and a rk_sandbox_... key.

3.1 Create a Customer

From API Reference → POST /customers → Try it:

{
  "email": "alice@example.com",
  "name": "Alice Example",
  "phone": "+44 7700 900000",
  "metadata": {
    "source": "playground"
  }
}

You should receive a 201 Created response with a customer.id (UUID).

3.2 Create a Product

From POST /products:

{
  "name": "Premium Membership",
  "description": "Access to all classes",
  "price_cents": 4900,
  "currency": "gbp",
  "billing_interval": "month",
  "billing_interval_count": 1,
  "trial_period_days": 14,
  "metadata": {
    "segment": "membership"
  }
}

Note the returned product.id.

3.3 Create a Subscription

From POST /subscriptions. Use the customer_id and product_id from previous steps:

{
  "customer_id": "uuid-of-customer",
  "product_id": "uuid-of-product",
  "collection_method": "charge_automatically",
  "trial_period_days": 14,
  "metadata": {
    "playground": "true"
  }
}

You should see status: "trialing" (if trial days are set), or status: "active" after a successful initial charge.

3.4 Create a Checkout Session

From POST /checkout/sessions:

{
  "mode": "subscription",
  "product_id": "uuid-of-product",
  "customer_email": "alice@example.com",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "metadata": {
    "demo": "playground"
  }
}

You'll receive a url field that you can open in a browser to walk through the hosted checkout UX.

4. Switching Environments in the Playground

The Playground supports all three environments defined in the OpenAPI spec:

5. Handling Errors in the Playground

Common errors you might see:

5.1 401 Unauthorized

• Missing or invalid x-revkeen-key
• Key was deleted or rotated
• Key prefix does not match the chosen environment

5.2 429 Too Many Requests

You exceeded your current plan's rate limits. Check headers:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

5.3 Validation Errors (400 Bad Request)

The response body follows the Error schema:

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_field",
    "message": "customer_id is required",
    "param": "customer_id",
    "doc_url": "https://docs.revkeen.com/api-reference"
  }
}

Use this to quickly adjust the payload in the Playground and resend.

6. Best Practices for Using the Playground

• Prefer Sandbox keys (rk_sandbox_) for all interactive testing.
• Use the Playground to:
  • Prototype integrations
  • Inspect real JSON responses
  • Understand filters and pagination
• Once comfortable, switch to using the SDK for type-safe integration.

import { RevKeenClient } from "@revkeen/sdk";

const rk = new RevKeenClient({
  apiKey: process.env.REVKEEN_API_KEY!,
  environment: "sandbox",
});

const res = await rk.customers.list({ page: 1, limit: 20 });

7. Where to Go Next