API Reference

POST events

Ingest one or more events into the monitoring timeline. Events land as custom:<app-slug> rows grouped per worker. Batch limit: 100 events, body ≤ 1 MB.

Endpoint

POST/api/v1/ingest/events

Headers

Field	Type	Notes
Authorization	Bearer	Required.
Content-Type	application/json	Required.
Idempotency-Key	string ≤ 200	Recommended. Replay-safe for 10 min.

Request body

Field	Type	Notes
events	IngestEvent[]	Required. 1 ≤ len ≤ 100.
events[].eventType	string	Required. Must be whitelisted for this app.
events[].category	EventCategory	Required. One of: PRESENCE, COMMUNICATION, CODE_CHANGE, CODE_REVIEW, TASK_UPDATE, MEETING, DOCUMENT, AI_TASK.
events[].actor	Actor	Required. workerId, externalId, or email.
events[].timestamp	ISO 8601	Optional. Defaults to now.
events[].duration	integer seconds	Optional. 0 ≤ d ≤ 86400.
events[].pillar	StatisticPillar	Optional override for rollup pillar.
events[].statisticId	string	Optional. Must exist in app manifest.
events[].metadata	object	Optional. ≤ 16 KB JSON.

Actor

Field	Type	Notes
workerId	string	Existing WePeople Worker.id.
externalId	string	Your stable id (preferred). Max 200 chars.
email	string	Org directory match (last resort).
displayName	string	Used when auto-provisioning a worker.

Example

curlbash

curl -X POST "https://wepeople.app/api/v1/ingest/events" \
  -H "Authorization: Bearer $WEPEOPLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-batch-8412" \
  -d '{
    "events": [
      {
        "eventType": "ticket.resolved",
        "category": "TASK_UPDATE",
        "actor": { "externalId": "crm-user-42" },
        "duration": 240,
        "metadata": { "ticket_id": "SUP-431" }
      }
    ]
  }'

Response 202 / 207

Full success: 202 Accepted. Partial success: 207 Multi-Status — inspect results.rejected[].index to retry only failed rows.

application/jsonjson

{
  "requestId": "req_01HP3K5V4J3M9NVT8XZKQ9YQ2E",
  "accepted": 2,
  "rejected": 1,
  "batchLimit": 100,
  "results": {
    "accepted": [
      { "eventType": "ticket.resolved", "timestamp": "2026-04-19T12:05:00Z" },
      { "eventType": "ticket.resolved", "timestamp": "2026-04-19T12:06:10Z" }
    ],
    "rejected": [
      {
        "index": 2,
        "code": "forbidden_event_type",
        "message": "eventType 'deploy.shipped' is not whitelisted."
      }
    ]
  }
}

Errors

forbidden_event_type (403) — type not in app whitelist
batch_too_large(413) — > 100 events or body > 1 MB
missing_actor / worker_not_found — actor resolution failed
invalid_body (400) — schema validation
rate_limited (429) / quota_exceeded (402)

Full table: Error codes. Guide: Ingest guide.

Field

Type

Notes

Authorization

Bearer

Required.

Content-Type

application/json