采集 API

一切始于一个事件。把它发送到采集端点，引擎立即将其折叠进实时用户状态。完整的 SDK 与 API 参考随产品一同发布。

At a glance

Host: eu.api.prodantix.com
Operations: POST /v1/events · POST /v1/identify · POST /v1/group
Credential: The public project key, as a Bearer header or api_key in the body
Answer: 202: accepted for processing

Send a batch

Events travel in batches, one request carrying 1 to 1000 of them. The body is strict: an unknown key anywhere, a missing field or an out-of-bounds value rejects the whole batch with 400 INVALID_EVENT_BATCH. A missing or invalid key answers 401; a key from another region answers 403.

curl -X POST "https://eu.api.prodantix.com/v1/events" \
  -H "Authorization: Bearer $PRODANTIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "distinct_id": "u_8f3a",
      "event_id": "5f6b2c1e-8f4b-4c6e-9d2a-7b1e3c4d5a6f",
      "event_name": "order.completed",
      "properties": { "amount": 4200 },
      "schema_version": 1,
      "timestamp": "2026-08-31T12:00:00.000Z"
    }],
    "sent_at": "2026-08-31T12:00:01.000Z"
  }'

await fetch('https://eu.api.prodantix.com/v1/events', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    events: [
      {
        distinct_id: 'u_8f3a',
        event_id: crypto.randomUUID(),
        event_name: 'order.completed',
        properties: { amount: 4200 },
        schema_version: 1,
        timestamp: new Date().toISOString(),
      },
    ],
    sent_at: new Date().toISOString(),
  }),
});

final response = await http.post(
  Uri.parse('https://eu.api.prodantix.com/v1/events'),
  headers: {
    'Authorization': 'Bearer $apiKey',
    'Content-Type': 'application/json',
  },
  body: jsonEncode({
    'events': [
      {
        'distinct_id': 'u_8f3a',
        'event_id': '5f6b2c1e-8f4b-4c6e-9d2a-7b1e3c4d5a6f',
        'event_name': 'order.completed',
        'properties': {'amount': 4200},
        'schema_version': 1,
        'timestamp': '2026-08-31T12:00:00.000Z',
      }
    ],
    'sent_at': '2026-08-31T12:00:01.000Z',
  }),
);

response = requests.post(
    "https://eu.api.prodantix.com/v1/events",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "events": [
            {
                "distinct_id": "u_8f3a",
                "event_id": "5f6b2c1e-8f4b-4c6e-9d2a-7b1e3c4d5a6f",
                "event_name": "order.completed",
                "properties": {"amount": 4200},
                "schema_version": 1,
                "timestamp": "2026-08-31T12:00:00.000Z",
            }
        ],
        "sent_at": "2026-08-31T12:00:01.000Z",
    },
)

Field	Required	Rules
events	Yes	1 to 1000 events per request
sent_at	Yes	ISO-8601 with an explicit offset, stamped when the batch left the client
api_key	No	The public project key (pdx_pub_…); an alternative to the Authorization header

The event envelope

Each entry in events is one envelope. What the fields mean for the person they describe is the data model; the wire rules are:

Field	Required	Rules
distinct_id	Yes	1 to 200 characters; the user the event belongs to
event_id	Yes	A UUID minted by the sender, one per event
event_name	Yes	1 to 200 characters, lowercase dotted (order.completed); a leading $ is reserved for platform names
timestamp	Yes	ISO-8601 with an explicit offset, stamped when the event happened
schema_version	Yes	Always 1
properties	No	Any JSON object, defaults to empty; $set, $set_once and $unset mutate user state
session_id	No	1 to 200 characters; ties the event to a replay session
context	No	locale, os, sdk and sdk_version, each optional and bounded

Identify and group

Two dedicated operations write identity rather than behaviour. POST /v1/identify associates traits with a distinct id and merges identities; POST /v1/group associates a distinct id with a group. Both take a loose { distinct_id, event_id?, properties?, timestamp? } body, become $identify and $group system events inside the engine, and answer 202 like the batch endpoint. How a merge resolves is described in the data model.

已接受不等于已持久化

采集类操作返回 202。这表示事件已被接受以待处理，而非已经持久化。格式错误的事件可能在后续处理中被丢弃。

To confirm an event survived the pipeline, read it back from the events query as the quickstart does, or watch it arrive on the project room (realtime events).

Where this meets the rest of the docs

The SDKs wrap this endpoint, batching and retrying for you; install one rather than posting by hand where you can. The other REST operations, flags and messaging, live on the REST page, and the host serves its own contract at /openapi.json.