Server API
The API the server SDKs use, for any language: read your site's flags and "In your code" experiments, decide for a visitor, and send events. With an SDK you don't need it directly: see Server-side SDKs.
Authentication
Every request sends one of the site's server keys: Authorization: Bearer sk_…. Make keys in Site settings → Server keys. A missing, unknown or revoked key gets 401. Keys are for servers only: the API doesn't answer browsers' cross-origin requests, so a key in a page wouldn't work, and would leak.
The base address is https://app.peekbird.com. Answers are JSON; errors are {"error": "…"} with a plain message.
Read flags and experiments
GET /api/v1/config answers the site's feature flags and running "In your code" experiments, with the audiences they use:
curl https://app.peekbird.com/api/v1/config \
-H "Authorization: Bearer $PEEKBIRD_KEY"{
"version": 1,
"siteId": "site_4k2m9x1q7z3a",
"settings": { "cookieDays": 365, "consent": "regional" },
"experiments": [
{ "id": "exp_…", "key": "one-page-checkout", "seed": "…", "status": "running", "traffic": 10000,
"variations": [{ "id": "var_…", "key": "control", "weight": 5000 },
{ "id": "var_…", "key": "one-page", "weight": 5000 }] }
],
"flags": [{ "id": "flag_…", "key": "new-search", "seed": "…", "enabled": true, "rollout": 2500 }],
"audiences": []
}An experiment in a mutually exclusive group also carries group: its share of the group's visitors, and the group's other tests.
It carries an ETag: send it back as If-None-Match, and an unchanged config answers 304 with nothing to download. The SDKs ask every 30 seconds. Deciding from it locally means following Peekbird's rules exactly (the hash, audiences, consent): the SDKs do, and every one is tested against the same cases.
Decide over HTTP
POST /api/v1/decide decides here, for a language without an SDK. It costs a request per decision, so prefer an SDK where there is one.
curl https://app.peekbird.com/api/v1/decide \
-H "Authorization: Bearer $PEEKBIRD_KEY" \
-H "Content-Type: application/json" \
-d '{"visitor": {"id": "VISITOR_ID", "country": "US", "attributes": {"plan": "pro"}},
"experiments": ["one-page-checkout"], "flags": ["new-search"]}'
# → {"experiments": {"one-page-checkout": "one-page"},
# "flags": {"new-search": true},
# "assignments": "exp_…:var_…"}visitor:id, and what you know:attributes,url,userAgent,language,country,region,regionCode,city,referrer,cookies(the request's, by name),timeZone,gpc,consent,qa.experimentsandflags: the keys to decide; every one when left out. An unknown key answersnullorfalse.forced: variations to show whatever the audience, by experiment key, for previews (counted as QA).track:trueby default, counting each variation decided as seen and noting each flag's answer.falsedecides only.assignmentsin the answer is the_peekbird_expcookie's new value: set it, and the browser keeps the same variations.
Send events
POST /api/v1/events takes up to 100 events, each naming its visitor:
curl https://app.peekbird.com/api/v1/events \
-H "Authorization: Bearer $PEEKBIRD_KEY" \
-H "Content-Type: application/json" \
-d '{"events": [
{"type": "event", "visitorId": "VISITOR_ID", "name": "purchase",
"revenue": 49.9, "currency": "USD", "orderId": "ORDER-123"},
{"type": "identify", "visitorId": "VISITOR_ID", "userId": "42", "email": "[email protected]"}
]}'
# → 202 {"received": 2, "dropped": 0}| Field | What it is |
|---|---|
| type | event, identify, exposure, flag or attributes. |
| visitorId | Who it's about: the browser's _peekbird_uid cookie, or your own ID for them (up to 64 characters). |
| sessionId | Optional: the browser's _peekbird_sid cookie, to put the event in their visit. One a day otherwise. |
| ts | Optional: when it happened, in milliseconds since 1970. Now otherwise. |
| url | Optional: the page it was about. |
| qa | Optional: true for a QA visitor, kept apart from results and analytics. |
| userAgent, country, region, city | Optional: the visitor's browser and location, for device and country reports. |
| name, revenue, value, currency, orderId, properties | event: as in the page (see Purchases and Other events). Each order counts once, by its ID. |
| userId, email, name | identify: who the visitor is (see Who the visitor is). |
| experimentId, variationId | exposure: the visitor saw a variation (the SDKs send these for you). |
| flagId, on | flag: the answer a visitor got from a flag that's switched on, true or false (the SDKs send these for you). |
| attributes | attributes: facts about the visitor, for analytics filters. |
- It answers
202with how many were received and dropped. A malformed event is dropped with the reason (inproblems); the others are kept. A request with none valid answers400. - Events are stored as the page's are: each order once, by its ID; checkout steps once a visit. Over your plan's tracked visits, they're dropped (the answer says
"paused": true), as the page's are. - Send events only for visitors who agreed, where your site waits for consent. The SDKs check this for you (see Consent).
Limits
| Endpoint | Limit |
|---|---|
| GET /api/v1/config | 300 a minute per key |
| POST /api/v1/events | 3,000 a minute per key, 100 events each |
| POST /api/v1/decide | 12,000 a minute per key |
Past one, the answer is 429 with Retry-After. The SDKs stay far below them: they decide locally and send events in batches.
