generated: '2026-08-13'
method: searched
source: >-
  https://developer.dreamdata.io/server-side/server-side-tracking/ +
  https://developer.dreamdata.io/client-side/api/ +
  https://developer.dreamdata.io/server-side/nodejs-sdk/ +
  https://developer.dreamdata.io/mcp/mcp-server/
checked: '2026-08-13'
api: Dreamdata Event Tracking API + MCP server + outbound webhook syncs
authentication:
  server_side: HTTP Basic (source API key as username, empty password), base64-encoded "apiKey:"
  client_side: Browser JavaScript library initialized with the account-specific write key / source id
  mcp: OAuth 2.1 authorization code + PKCE (S256), bearer token in the Authorization header
  key_location: Data Platform > Sources > Server Side Analytics APIs (in-app)
  cross_link: authentication/dreamdata-authentication.yml
event_model:
  spec_family: Segment-compatible (track, page, identify, group, alias)
  batch_endpoint: POST https://api.dreamdata.cloud/v1/batch
  content_type: application/json
  max_request_size: 500kb
  envelope_fields:
  - messageId (envelope-level, per batch)
  - sentAt (ISO 8601, when the batch left the client)
  - batch (array of events)
  required_event_fields:
  - type
  - messageId
  - userId or anonymousId
  - timestamp
  mixed_batches: >-
    A single batch may mix identify, track and page events — the docs show an identify and a
    track in one request for a form_fill.
  client_vs_server: >-
    The same tracking API backs both sides. Client-side methods take positional arguments and
    the library attaches anonymousId and context automatically; server-side methods take a
    single object and the caller must supply userId or anonymousId itself.
idempotency:
  supported: false
  header: null
  detail: >-
    No Idempotency-Key header, no retention window and no replay contract is documented. Each
    event carries a unique messageId (UUID) as the Segment spec requires, and the SDKs retry
    automatically, but Dreamdata nowhere states that messageId is used for server-side
    deduplication of retried batches. Because the guarantee is not published, no Idempotency
    pointer is claimed in apis.yml — an agent cannot safely assume a retried batch is deduped.
  cross_link: null
deduplication:
  field: messageId
  scope: per event
  note: >-
    Unique per event and, separately, on the batch envelope. Its role is identification per the
    Segment spec; deduplication semantics are not documented by Dreamdata.
timestamps:
  format: ISO 8601
  fields:
  - timestamp (per event, when it occurred; defaults to now in the SDKs)
  - sentAt (per batch, when the batch was sent)
identity:
  user: userId (authenticated/known) or anonymousId (visitor)
  requirement: at least one of userId or anonymousId per event
  anonymous_id_server_side: >-
    For purely server-side integrations the caller must generate and persist anonymousId
    itself; the docs suggest a session-stored UUID.
  company: group (groupId) — account-based B2B analytics
  alias: alias links an anonymous identity to a known userId (previousId)
context:
  fields:
  - ip
  - userAgent
  - page (url, referrer, title)
  - campaign (name, source, medium, term, content)
  - library (name, version)
  note: Context is attached automatically client-side and supplied by the caller server-side.
pagination:
  applicable: false
  note: >-
    The public HTTP surface is write-only ingestion — there is no public read API to paginate.
    Reads happen through the data warehouse (SQL) or the MCP tools, neither of which documents
    a pagination contract.
versioning:
  scheme: uri-path
  current: v1
  cross_link: lifecycle/dreamdata-lifecycle.yml
request_tracing:
  request_id_header: null
  note: No request-id or correlation header is documented on any surface.
error_envelope:
  tracking_api: not documented
  mcp: 'JSON {"error", "error_description"} plus an RFC 6750 WWW-Authenticate: Bearer challenge'
  cross_link: errors/dreamdata-error-codes.yml
rate_limit_signalling:
  headers: none published
  cross_link: rate-limits/dreamdata-rate-limits.yml
retries:
  sdk: >-
    Both first-party SDKs batch, retry and flush on graceful shutdown automatically; the policy
    (attempt count, backoff, retryable statuses) is not published.
outbound_webhooks:
  signing: HMAC-SHA256 signature appended to each request; signing key retrievable per sync
  custom_headers: optional key/value HTTP headers for destination auth
  operations: [Insert, Upsert]
  cadence: initial full sync, then daily after each data-modeling run
  cross_link: asyncapi/dreamdata-webhook-syncs.yml
mcp_conventions:
  tool_selection: >-
    The provider states tools are never called by name by the user — the agent selects them
    from natural language. Several tools are explicitly documented as "behind the scenes"
    discovery calls (filter properties, filter values, config schema, report components).
  consent_split: >-
    Read is a required consent; saving reports is a separate optional consent (reports:write)
    that cannot modify or delete existing reports, and the client is expected to confirm each
    save with the user.
  account_selection: >-
    One URL for all accounts; when a user belongs to several, list_my_accounts resolves which
    account a request runs against.
  cross_link: mcp/dreamdata-mcp.yml
content_security_policy:
  script_src: "'self' 'unsafe-inline' https://cdn.dreamdata.cloud https://cdn.drda.io"
  connect_src: https://cdn.dreamdata.cloud
  source: https://developer.dreamdata.io/client-side/csp/