Skip to content
Peekbird

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.
  • experiments and flags: the keys to decide; every one when left out. An unknown key answers null or false.
  • forced: variations to show whatever the audience, by experiment key, for previews (counted as QA).
  • track: true by default, counting each variation decided as seen and noting each flag's answer. false decides only.
  • assignments in the answer is the _peekbird_exp cookie'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}
FieldWhat it is
typeevent, identify, exposure, flag or attributes.
visitorIdWho it's about: the browser's _peekbird_uid cookie, or your own ID for them (up to 64 characters).
sessionIdOptional: the browser's _peekbird_sid cookie, to put the event in their visit. One a day otherwise.
tsOptional: when it happened, in milliseconds since 1970. Now otherwise.
urlOptional: the page it was about.
qaOptional: true for a QA visitor, kept apart from results and analytics.
userAgent, country, region, cityOptional: the visitor's browser and location, for device and country reports.
name, revenue, value, currency, orderId, propertiesevent: as in the page (see Purchases and Other events). Each order counts once, by its ID.
userId, email, nameidentify: who the visitor is (see Who the visitor is).
experimentId, variationIdexposure: the visitor saw a variation (the SDKs send these for you).
flagId, onflag: the answer a visitor got from a flag that's switched on, true or false (the SDKs send these for you).
attributesattributes: facts about the visitor, for analytics filters.
  • It answers 202 with how many were received and dropped. A malformed event is dropped with the reason (in problems); the others are kept. A request with none valid answers 400.
  • 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

EndpointLimit
GET /api/v1/config300 a minute per key
POST /api/v1/events3,000 a minute per key, 100 events each
POST /api/v1/decide12,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.

See what your visitors see.

Start free in a few minutes: one snippet, every feature. Move to a bigger plan when you need more tracked visits.