Quickstart
Get a key, make your first call with cURL, TypeScript or Python, and read the response envelope.
Last updated
On this page
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).
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
- Create an account. 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.
- 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. - Copy the secret. It starts with
pa_live_and is shown once; we only store a hash of it.
An agent can mint its own trial key. No account, email or card is involved:
curl -sS -X POST "https://api.primaryapi.com/agent/signup" \
-H "Content-Type: application/json" \
-d '{"label":"research-agent"}'{
"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:
export PRIMARYAPI_API_KEY="pa_live_…"Make your first call
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":"[email protected]"}'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: '[email protected]' }),
});
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
}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": "[email protected]"},
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 freeThe body is the SKU's input. Each API's input fields are listed on its reference page 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
{
"output": {
"found": true,
"data": { "email": "[email protected]", "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:
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":"[email protected]"}'{
"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).