Skip to main content

SDK Contract

SDK Contract​

SDKs must send tenant-bound, authenticated event payloads to the ingest API.

Use the public Custd SDK repository for JavaScript/TypeScript, React, Go, PHP and Python installation instructions and release notes. Select one released version for your application; do not copy a transport implementation out of an example. The examples in this site describe the current v2 SDK family.

Tenancy and auth​

  • Tenant is derived from the auth token company_slug claim.
  • companySlug in the payload is optional, but if present must match the token tenant.
  • SDKs send Authorization: Bearer <token> on ingestion calls.
  • Machine event writers need events.write; a generic admin scope does not grant every capability.
  • Keep confidential client secrets on your server. Browser tracking uses its separate site/write-key contract.

Endpoints​

  • POST /api/v1/events
  • POST /api/v1/events/batch

Batch responses include per-event results[]. A response with success: false means at least one event failed, and SDKs must surface the flush as failed after retaining the unsent batch for retry. Check the result count, each status and each event UUID; HTTP 202 by itself is not acceptance proof. Correct validation failures before resending, and preserve event identity when retrying. Use the SDK's bounded retry behavior for transient failures instead of an unbounded application loop.

Accepted events are durable in S3 and the core ledger before acknowledgement. Queries become ready after asynchronous Parquet preparation; acceptance is not an immediate query-readiness guarantee. See Ready data.

Measurement admin helpers​

The released SDKs expose typed measurement operations. See measurement setup for a worked process; consult your language's release reference for exact method signatures.

  • Create/list/get measurement projects through /api/v1/admin/measurement/projects.
  • Submit structured rows through /api/v1/admin/measurement/projects/{projectSlug}/observations:bulk.
  • Import CSV strings through /api/v1/admin/measurement/projects/{projectSlug}/observations:csv.

SDK helpers validate that measurement import responses contain one result per submitted row and that every successful row includes observationUuid; failed rows keep their RFC 9457 problem fields visible.

Choose the right workflow​

For API field names and response shapes, use Generated OpenAPI. SDK coverage and user permissions are separate: a helper being available does not authorize the token to call it.