Quickstart

Orders, signups, and refunds should be sent from your server, not from the visitor's browser. Sending the same idempotency key again does not add a row, so a failed call is safe to replay.

Prerequisites

You are an Owner or Admin. The key needs the Server track scope. Never paste a full key into a repo or a doc.

Steps

1. Create a key

   Open ConsoleConfigurationSettingsAPI keys and include Server track. The key starts with wck_ and is shown only at creation.

2. Send one event

   POST /api/v1/track with JSON. Set Authorization to Bearer wck_… without the rest of the secret. insert_id is at most 36 characters. time is milliseconds. When it is more than 72 hours from the server clock, the server uses the current time, adds a warning, and still accepts the event by default.

   curl -X POST "https://YOUR_ORIGIN/api/v1/track" \
     -H "Authorization: Bearer wck_…" \
     -H "Content-Type: application/json" \
     -d '{"events":[{"event":"purchase","login_id":"u_123","insert_id":"order-1001","properties":{"revenue":19.9}}]}'

3. Read the response

   accepted is the number of events that passed validation and were written to the buffer. When rejected is above 0, the results carry a reason, such as a missing event name. debug=1 validates and does not store.

Verify

purchase shows on ConsoleAll-platform analyticsDataEvents & properties or ConsoleWeb analyticsEvents. An event with login_id can appear under that user.

An event without a session id stays on the event table and is not counted as a new website visit. To attach it to a pageview, send that visit's session id.

Common failures

A missing or invalid key, or one without the Server track scope, returns 401. A missing event name is rejected. POST /api/v1/server/events is a different channel: it keeps bot hits only and will not record an order. See Server events & log import.

Server events & log import

Only the business-event endpoint writes orders and signups. The other two keep requests classified as bots, which is how you see crawlers that never run the script.

Keys are created on ConsoleConfigurationSettingsAPI keys. The three endpoints need the Server track, Write server events, and Import logs scopes respectively. Every call uses Authorization: Bearer wck_….

Three endpoints

• POST /api/v1/track writes business events.
• POST /api/v1/server/events submits access records; human requests are counted in skippedHuman and dropped.
• POST /api/v1/server/logs/import accepts Nginx / Apache combined-format log lines. A line that does not parse is not counted as parsed.

Parameters

A business body is { "events": [ … ] }, from 1 to 1000 items. Common fields:

Field	Required	Meaning
type	No	Defaults to track. Other types update a profile, bind an id, or patch by idempotency key
event	Yes for a behavior	At most 100 characters
insert_id	Yes when updating	At most 36 characters. A normal resend does not add a row; the first one stays
session_id	No	At most 32 characters. Empty means the row is not a session
login_id	No	Binds a user. The type defaults to login id
time	No	Milliseconds. More than 72 hours from the server is rewritten to the current time and warned; it is not rejected by default
properties	No	Keys at most 50 characters. Values are string (at most 1000 characters), number, boolean, or null

Each access record needs ua and url. Optional fields are ts, ip, method, status, responseTime, and referrer. Log import accepts at most 5000 lines, each at most 4000 characters.

Defaults & limits

Business events and access records allow at most 1000 items per call, and log import at most 5000 lines; a request over the limit is rejected at validation, not silently truncated. A business event without session_id stays on the event table and does not open a session. debug=1 validates only. The platform defaults to server.

Example

The smallest business request is in Server events quickstart. An access record:

curl -X POST "https://YOUR_ORIGIN/api/v1/server/events" \
  -H "Authorization: Bearer wck_…" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"ua":"Mozilla/5.0 (compatible; ExampleBot/1.0)","url":"https://example.com/"}]}'

Errors

A missing or invalid key, or one without the scope, returns 401. A normal browser user agent sent to the access-record API is skipped as human and never shows on a report. An update without insert_id is rejected.