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

# Concepts

> The handful of ideas behind the platform: organizations, API keys, prepaid credits, and one OpenAI-compatible endpoint.

## Control plane and data plane

The platform splits into two surfaces:

* The **control plane**, this dashboard and its management API: your organization, members, API keys, credits, billing, and usage analytics.
* The **data plane**, the inference endpoint your applications call. It is OpenAI-compatible, powered by GPU capacity across the Pearl network:

```text Base URL theme={null}
https://inference.pearlresearch.ai/v1
```

Your SDK and API traffic goes straight to the data plane with a Pearl API key; nothing you ship routes through the dashboard.

## Organizations and roles

An **organization** is the top-level resource: API keys, credits, usage, and billing all belong to it, and every member's usage draws from the same balance. You create one when you sign up, and invite teammates from the [Organization](https://platform.pearlresearch.ai/organization) page. Each member has a role that scopes what they can do: `org-admin` has full control, `billing-admin` covers credits and payments, `developer` covers day-to-day API work, and `viewer` is read-only.

## Inference regions

Every organization has an **inference region**, and it decides which inference endpoints its API keys can reach. New organizations start on **Global**. On Enterprise accounts, an organization admin (`org-admin`) can move the organization to **EU** under Data residency on the [Settings](https://platform.pearlresearch.ai/settings) page.

| Region | What its keys reach |
| - | - |
| Global | Any region, through the base URL above. |
| EU | The EU deployment only, through the EU base URL. |

**Global** is a routed endpoint: it spreads requests across the regional deployments, and which region answers any given request is not guaranteed. Pick **EU** when your traffic has to stay in one region.

A regional organization is pinned to its region: its keys are accepted at that region's endpoint and rejected everywhere else, and a request never falls back to another region. Your region's base URL is shown on the Settings page, and the model catalog, the playground, and the dashboard's SDK examples all follow it. Switching regions changes that URL, so update your clients afterwards; keys, credits, and billing are untouched. See [Data residency](/docs/data-residency.md) for the regional endpoints and how to pin your organization to a region.

> [!NOTE]
>
> These docs always show the Global base URL. If your organization is on EU, swap in the base URL from your Settings page.

## API keys

API keys authenticate your requests to the data plane. They are organization-scoped, prefixed `sk-prl-infapi-`, and shown in full exactly once at creation, we store only a digest, so a lost key means minting a new one. Manage them on the [API Keys](https://platform.pearlresearch.ai/api-keys) page:

* **Revoke** disables a key. It stays listed as revoked so you can see what was shut off, and stops being accepted within a couple of minutes.
* **Delete** removes the key from your dashboard entirely. Usage it already generated stays attributed in your analytics.

## Credits and billing

The platform runs on **prepaid USD credits**. Inference is metered per token, input, cached input, and output tokens are each priced per million, and drawn down from your organization's balance as you go. There are no subscriptions or minimums.

* New organizations receive a \$1 welcome credit to start experimenting, a promotion that may change or be discontinued at any time.
* Top up from the [Billing](https://platform.pearlresearch.ai/billing) page (\$5 to \$4,999 per top-up) via Stripe-hosted checkout, card details never touch our servers.
* Optional **auto-recharge** tops the balance up automatically when it dips below a threshold you set.
* When credits run out, requests are declined until you top up. Enterprise organizations can instead be invoiced monthly, contact us to switch.

## Models and the network

The catalog is a curated set of production open-weight models, see [Models](/docs/models.md). Models are served on the Pearl network's distributed GPU capacity rather than a single provider's cluster, behind one OpenAI-compatible endpoint. The platform currently serves chat models; the live list (with per-model context lengths and supported parameters) is always at `GET https://inference.pearlresearch.ai/v1/models`.

## OpenAI compatibility

Any OpenAI SDK works by changing two constructor arguments, the base URL and the API key. No other code changes are required.

| Endpoint | Status |
| - | - |
| `POST /chat/completions`, including streaming, tools, JSON mode, and image input | Supported |
| `POST /completions`, including streaming | Supported |
| `GET /models` | Supported |

### Request parameters

Models accept the standard sampling parameters, `temperature`, `top_p`, `frequency_penalty`, `presence_penalty`, `stop`, `seed`, and `max_tokens`, plus `top_k` and `min_p` extensions (pass those via `extra_body` in the OpenAI SDKs). Support varies slightly per model; the `supported_sampling_parameters` field on `GET /models` is authoritative.

> [!NOTE]
>
> Model IDs are namespaced (for example `deepseek-ai/DeepSeek-V4-Pro-0813`), not flat names like `gpt-4o`, remember to update the `model` parameter when migrating.

## Playground

The [playground](https://platform.pearlresearch.ai/playground) is an in-browser chat over the same catalog. Playground traffic is billed to your organization like any API call, so what you see there, behavior, latency, cost, is what your application gets.

## Glossary

| Term | Definition |
| - | - |
| Token | The unit models read and write, roughly ¾ of an English word. Usage and pricing are metered per token. |
| Context window | The maximum number of tokens (prompt + response) a model can consider in one request. |
| Streaming | Receiving the response token by token as it is generated, instead of waiting for the full reply. |
| Function calling (tools) | Letting the model request that your code run a function, then continue with its result. |
| Structured outputs (JSON mode) | Constraining the response to valid JSON so it can be parsed by machines. |
| Reasoning model | A model that thinks before answering and returns that thinking in a separate reasoning field. |
| Cached input tokens | Prompt-prefix tokens the network has recently processed for you, metered separately at a discounted rate. |
| Quantization | The numeric precision a model is served at (fp4, fp8, int8), lower precision trades a little quality for speed and cost. |


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