# Your first API call in 2 minutes

> One path from nothing to a real API answer: sign in, create a free sandbox with 30 synthetic patients, copy the key and make one call in curl, Python, JavaScript or Dart, with the expected result and the usual errors.

Source: https://developers.anpheros.com/guides/first-api-call

One path from nothing to a real answer from the API: an account, a sandbox, a key and one call.
The sandbox is free, needs no card, and comes with 30 synthetic patients, so you never touch real
patient data while you build.

**In short:**

| Step | What you do | Time |
|---|---|---|
| 1. Account | Sign in on the dashboard with Google | 20 s |
| 2. Sandbox | Press **Get a sandbox key** | 10 s |
| 3. Key | Copy the `sk_test_…` key (shown once) | 10 s |
| 4. Call | Run one request: curl, Python, JavaScript or Dart | 30 s |
| 5. Check | You see 30 patients, starting with Elena Ionescu | 10 s |

<!-- visual:seq-first-call -->

## 1. Create your account

Open the dashboard at [platform.anpheros.com/dashboard](https://platform.anpheros.com/dashboard/?src=first-api-call&utm_source=developers.anpheros.com&utm_medium=guide&utm_campaign=first-api-call)
and sign in with Google. That is the whole account: no form, no card.

## 2. Create your sandbox

Press **Get a sandbox key**. You get an organization, a sandbox project and its own copy of 30
synthetic patients with six months of history: conditions (ICD-10), medications (ATC), allergies,
lab results and vital signs (LOINC). Nobody else sees your copy, and you can change or delete
anything in it.

## 3. Copy your key

The key starts with `sk_test_` and is shown **only once**. Copy it now and keep it on your
computer or server, never in an app you ship. If you lose it, create a new key in the dashboard
and revoke the old one.

Put it in your terminal so the examples below work as they are:

```bash
export ANPHEROS_KEY=sk_test_your_key_here
```

## 4. Make your first call

The base URL is `https://platform.anpheros.com` for the sandbox and for production: the key
decides which data you reach. Every request sends the key as `Authorization: Bearer <key>`.

**curl**

```bash
curl https://platform.anpheros.com/v1/patients -H "Authorization: Bearer $ANPHEROS_KEY"
```

**Python** (with `requests`: `pip install requests`)

```python
import os, requests

r = requests.get("https://platform.anpheros.com/v1/patients",
                 headers={"Authorization": f"Bearer {os.environ['ANPHEROS_KEY']}"})
r.raise_for_status()
body = r.json()
print(body["total"], "patients; first:", body["data"][0]["given"], body["data"][0]["family"])
```

**JavaScript** (Node 18 or newer, no package needed)

```js
const r = await fetch('https://platform.anpheros.com/v1/patients', {
  headers: { Authorization: `Bearer ${process.env.ANPHEROS_KEY}` },
});
if (!r.ok) throw new Error(`${r.status} ${await r.text()}`);
const body = await r.json();
console.log(body.total, 'patients; first:', body.data[0].given, body.data[0].family);
```

Save it as `first.mjs` and run `node first.mjs`. With the TypeScript SDK (`npm install @anpheros/sdk`):

```ts
import { Anpheros, apiKey } from '@anpheros/sdk';

const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });
const { data: patients } = await anpheros.patients.list();
console.log(patients.length, patients[0].given, patients[0].family);
```

**Dart / Flutter** (`dart pub add anpheros_sdk`; run it on your server or in a command-line tool, not inside a shipped app)

```dart
import 'dart:io';
import 'package:anpheros_sdk/anpheros_sdk.dart';

Future<void> main() async {
  final anpheros = Anpheros(auth: AnpherosAuth.apiKey(Platform.environment['ANPHEROS_KEY']!));
  final patients = await anpheros.patients.list();
  print('${patients.data.length} patients; first: ${patients.data.first.given} ${patients.data.first.family}');
}
```

## 5. What you should see

Status `200` and a list of your sandbox patients:

```json
{"data":[{"id":"…","given":"Elena","family":"Ionescu","birth_date":"1985-09-03","gender":"female",…,"fhir":"Patient/…"}, …],"total":30,"next_cursor":null}
```

`total` is 30 in a new sandbox. Each patient has an `id` you use in the next calls, and a `fhir`
reference to the same record in the FHIR R4 API. Try one more, with the `id` of the first patient:

```bash
curl "https://platform.anpheros.com/v1/patients/<id>/observations?category=laboratory&limit=5" \
     -H "Authorization: Bearer $ANPHEROS_KEY"
```

## 6. Next: your first write

Reading works, so write one value. This adds a glucose result to the patient whose `id` you used
above, says who the author is, and sends an `Idempotency-Key` so a retry never creates a duplicate:

```bash
curl -X POST "https://platform.anpheros.com/v1/patients/<id>/observations" \
     -H "Authorization: Bearer $ANPHEROS_KEY" -H 'content-type: application/json' \
     -H "Idempotency-Key: $(uuidgen)" -d '{
  "code": "2339-0", "display": "Glucose", "category": "laboratory",
  "value": 112, "unit": "mg/dL", "effective_at": "2026-09-19T08:10:00Z",
  "author_type": "device"
}'
```

The answer is the stored observation with its `id`, its `fhir` reference and `updated_at`. More
writes, documents and provenance: [Getting started](https://developers.anpheros.com/guides/getting-started).

## If it did not work

These are the answers people get most often on their first call. Every response carries an
`Anpheros-Request-Id` header: quote it if you write to us.

| You get | It means | Fix |
|---|---|---|
| `401` `Missing credentials: send an API key or an OAuth access token as 'Authorization: Bearer <token>'.` | The header is missing, or the word `Bearer` is missing before the key | Send `-H "Authorization: Bearer $ANPHEROS_KEY"`; check that `echo $ANPHEROS_KEY` prints your key. In the [API reference](https://developers.anpheros.com/docs), press **Authorize** and paste the key before **Try it out** |
| `401` `Invalid API key.` | The key is incomplete, has a space or quote in it, or was deleted | Copy it again; if it was shown only once and you lost it, create a new key in the dashboard |
| `401` `This API key has been revoked.` | Someone revoked the key in the dashboard | Create a new key |
| `404` `No such endpoint: GET /v1/patient.` | A typo in the path | Use the exact path from the [API reference](https://developers.anpheros.com/docs), for example `/v1/patients` |
| `404` `{"detail":"Not Found"}` | The path does not start with `/v1`, `/fhir/R4` or `/oauth` (for example `/api/v1/…`) | Remove the extra prefix |
| `429` `Rate limit of … requests/minute exceeded for this credential.` | Too many requests in one minute | Wait the number of seconds in the `Retry-After` header; the SDKs do this for you |

More answers, with examples: [Troubleshooting](https://developers.anpheros.com/guides/troubleshooting).

## Next steps

You have made the first of five steps. The bar at the top of these guides shows where you are:

1. **Quickstart**: this page.
2. **First write**: add an observation with its author and an `Idempotency-Key`, in [Getting started](https://developers.anpheros.com/guides/getting-started).
3. **OAuth app**: when your app acts for a real person, the person signs in and approves access: [Authentication and OAuth](https://developers.anpheros.com/guides/authentication).
4. **Webhooks**: get told when a record changes instead of polling: [Webhooks](https://developers.anpheros.com/guides/webhooks).
5. **Go live**: from the sandbox to production with real patients: [Go live](https://developers.anpheros.com/guides/go-live).

Along the way: read and share a patient summary with [IPS and SMART Health Links](https://developers.anpheros.com/guides/share-patient-summary), or let an AI coding tool write the integration with [Build with Claude Code or Cursor](https://developers.anpheros.com/guides/build-with-claude-code).

## Frequently asked questions

### Is the sandbox really free?
Yes. The sandbox is free, with no card and no time limit. You pay only for production, from €99 a month, and the first month of production is free.

### Can I use real patient data in the sandbox?
No. The sandbox is for synthetic patients and test data. Real patients go in a production project, after your organization is verified and has signed the data processing agreement.

### Do I need the FHIR API or the REST API?
Either. `/v1` is a simple REST API and `/fhir/R4` is strict FHIR R4. Both read and write the same records with the same ids, and the same key works for both.

### Where do I find every endpoint?
In the [API reference](https://developers.anpheros.com/docs) and in [openapi.json](https://developers.anpheros.com/openapi.json).