# Quickstart

Get a key, make your first call with cURL, TypeScript or Python, and read the response envelope.

> **Are you an AI agent?** Read `https://primaryapi.com/SKILL.md`: it covers setup, discovery, running calls and error handling in one file. If you have no key, `POST https://api.primaryapi.com/agent/signup` gives you a capped trial key without any human step (see [Agent self-signup](/docs/agent-signup)).

You need a terminal with `curl`, or Node.js 18+ (built-in `fetch`), or Python 3.9+ with `requests`. The examples call `email.verify`, a cheap validation API, but every SKU works the same way.

### Get an API key

**In the dashboard:**

1. [Create an account](https://primaryapi.com/sign-up). Your first workspace starts with 25 welcome credits, enough for a first round of calls: most calls cost 1 or 2 credits. Welcome credits can expire.
2. Open **Dashboard → API keys** and choose **Create key**. Keep the default access level, `run`, which can call APIs but cannot manage keys or read billing.
3. Copy the secret. It starts with `pa_live_` and is shown **once**; we only store a hash of it.

**As an agent:**

An agent can mint its own trial key. No account, email or card is involved:

```bash
curl -sS -X POST "https://api.primaryapi.com/agent/signup" \
  -H "Content-Type: application/json" \
  -d '{"label":"research-agent"}'
```

```json title="201 Created"
{
  "secret": "pa_live_…",
  "keyId": "key_01JBXM3T5V7Q9R2K4N6P8W0Y1Z",
  "expiresAt": "2026-11-06T14:05:09.120Z",
  "upgrade": {
    "claimUrl": "https://primaryapi.com/dashboard/authorize?claim=3f1c…",
    "authorizationServer": "https://api.primaryapi.com",
    "scope": "run balance:read"
  },
  "notice": "This is a free PrimaryAPI trial API key with … credits for API calls. It expires in 7 days …"
}
```

The response also carries `capCredits`, the trial budget in credits (trimmed above). Store `secret` without printing it, and pass `notice` to your human word for word. When the trial budget runs out, calls answer `402 trial_cap_reached` with the claim link; a person approves it and the same key keeps working.

Put the key in an environment variable so it never lands in code or logs:

```bash
export PRIMARYAPI_API_KEY="pa_live_…"
```

### Make your first call

```bash tab="cURL"
curl -sS -X POST "https://api.primaryapi.com/v1/run/email.verify" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com"}'
```

```ts tab="TypeScript"
const res = await fetch('https://api.primaryapi.com/v1/run/email.verify', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PRIMARYAPI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ email: 'person@example.com' }),
});

const body = await res.json();
if (!res.ok) throw new Error(`${body.code}: ${body.error} (request ${body.requestId})`);

if (body.output.found) {
  console.log(body.output.data.status, `cost ${body.credits} credits`);
} else {
  console.log('not found:', body.output.reason); // a valid answer, usually free
}
```

```python tab="Python"
import os
import requests

res = requests.post(
    "https://api.primaryapi.com/v1/run/email.verify",
    headers={"Authorization": f"Bearer {os.environ['PRIMARYAPI_API_KEY']}"},
    json={"email": "person@example.com"},
    timeout=30,
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['code']}: {body['error']} (request {body.get('requestId')})")

if body["output"]["found"]:
    print(body["output"]["data"]["status"], f"cost {body['credits']} credits")
else:
    print("not found:", body["output"]["reason"])  # a valid answer, usually free
```

The body is the SKU's input. Each API's input fields are listed on its [reference page](/docs/api-reference) and in `GET /v1/apis/{sku}` (no key needed). Unknown fields are rejected, not ignored, so a typo fails loudly and for free.

### Read the envelope

```json title="200 OK"
{
  "output": {
    "found": true,
    "data": { "email": "person@example.com", "domain": "example.com", "status": "good", "…": "…" }
  },
  "provider": "PrimaryAPI",
  "credits": 1,
  "items": 1,
  "requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z"
}
```

| Field | Meaning |
|---|---|
| `output.found` | `true` when the data exists. `false` is still a success: the account does not exist, is private, or a search matched nothing. |
| `output.data` | The result, shaped by the SKU's output schema. `null` when `found` is `false`. |
| `output.reason` | Why `found` is `false`: `not_found`, `private`, `no_results`, … |
| `credits` | What this call took from your balance, in whole credits. `0` when nothing was charged. |
| `items` | Billable results: the number of rows for per-result APIs, otherwise `1` for a hit and `0` for a miss. |
| `requestId` | Keep it. It identifies the call in your request history, in support requests and in `GET /v1/results/{id}`. |

Values in these examples are illustrative; each API's reference page shows its current price in credits.

### Optional: price a call before running it

`POST /v1/quote/{sku}` takes the same body, validates it and returns the price without calling any upstream or charging anything:

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/quote/email.verify" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com"}'
```

```json title="200 OK"
{
  "sku": "email.verify",
  "credits": 1,
  "maxCredits": 5,
  "unit": "request",
  "inputValid": true
}
```

`credits` is the expected price of the call; `maxCredits` is the most it can cost, which is what a run holds from your balance before it starts (the unused part comes back at once).

## What to read next

- [Authentication](https://primaryapi.com/docs/authentication): Access levels, spend limits per key, expiry and rotation.
- [Making requests](https://primaryapi.com/docs/making-requests): Input validation, not-found results and trimming large responses.
- [Durable requests](https://primaryapi.com/docs/durable-requests): What a 202 means, and how to poll for slow APIs.
- [Errors](https://primaryapi.com/docs/errors): Every error code with its cause and fix.
