> ## Documentation Index > Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt > Use this file to discover all available pages before exploring further. # Send server-side events > Ingest a batch of tracking events from your server. Each event is transformed into Upstack's canonical event and processed exactly like a pixel event — identity resolution, enrichment, analytics, and real-time forwarding to your configured destinations. Each event carries an event name, optional user data (identity traits), event data, and a few general context fields. Use a standard event name (e.g. `purchase`, `add_to_cart`) or your own custom name (`^[a-zA-Z][a-zA-Z0-9_]*$`). **Required scope:** `events:write`. ## OpenAPI ````yaml /api-reference/openapi.yaml post /tr/api/events openapi: 3.1.0 info: title: Upstack Data API version: '1.0' description: > Programmatic access to your Upstack Data pixel — analytics queries, the measures/dimensions catalog, and dashboard view management. All requests authenticate with two headers: - `x-api-key`: your Upstack API key (mint one at **Settings → API Keys** in the dashboard). - `x-pixel-id`: the pixel id the request targets. One key is scoped to one pixel. servers: - url: https://api.upstackdata.com description: Production security: - apiKey: [] pixelId: [] tags: - name: Analytics description: Query events, attribution, and cohort analyses. - name: Catalog description: List the measures available to your pixel. - name: Dashboards description: >- Manage dashboard views — create, update, copy, delete, and the high-level preset builder. - name: Account description: >- Read and update the account that owns this API key — display name, active owners and admins, and subscription summary. - name: Costs description: >- Read and update every cost surface — global product overrides, shipping method, per-variant handling fees and COGS history, and per-type cost lines (order / gateway / shipping profile / variable / fixed). Mutations trigger the same per-order COGS recalculation as web-UI changes. - name: Products description: Browse products + variants in the configured catalog. - name: Events description: Send server-side tracking events directly from your backend. paths: /tr/api/events: post: tags: - Events summary: Send server-side events description: | Ingest a batch of tracking events from your server. Each event is transformed into Upstack's canonical event and processed exactly like a pixel event — identity resolution, enrichment, analytics, and real-time forwarding to your configured destinations. Each event carries an event name, optional user data (identity traits), event data, and a few general context fields. Use a standard event name (e.g. `purchase`, `add_to_cart`) or your own custom name (`^[a-zA-Z][a-zA-Z0-9_]*$`). **Required scope:** `events:write`. operationId: createEvents requestBody: required: true content: application/json: schema: type: object required: - events additionalProperties: false properties: events: type: array minItems: 1 maxItems: 100 items: type: object required: - name additionalProperties: false properties: name: type: string pattern: ^[a-zA-Z][a-zA-Z0-9_]*$ maxLength: 100 description: Event name — a standard event or your own custom name. example: purchase user: type: object additionalProperties: false description: >- User data (identity traits). Describes the END USER, not your server. properties: emails: type: array items: type: string phones: type: array items: type: string userIds: type: array items: type: string genders: type: array items: type: string dobs: type: array items: type: string addresses: type: array items: type: object additionalProperties: false properties: email: type: string phone: type: string firstName: type: string lastName: type: string company: type: string address1: type: string address2: type: string city: type: string province: type: string provinceCode: type: string country: type: string countryCode: type: string zip: type: string data: type: object additionalProperties: true description: > Event data — the same shape the pixel and SDKs send. Any e-commerce (orderId, value, currency, items, …), SaaS (planName, mrr, …), or custom properties are accepted. ipAddress: type: string userAgent: type: string sessionId: type: string locale: type: string timezone: type: string page: type: object additionalProperties: false properties: host: type: string path: type: string referrer: type: string search: type: string title: type: string url: type: string qsp: type: object additionalProperties: true campaign: type: object additionalProperties: false properties: name: type: string campaign: type: string source: type: string medium: type: string term: type: string content: type: string click: type: object additionalProperties: false properties: fbc: type: string fbp: type: string gclid: type: string ttclid: type: string examples: purchase: summary: Purchase with user data, context, and event data value: events: - name: purchase user: emails: - jane@example.com userIds: - cust_889 ipAddress: 203.0.113.5 page: url: https://shop.com/checkout click: fbc: fb.1.abc gclid: xyz data: orderId: '10421' value: 99.9 currency: USD items: - id: SKU1 name: Tee price: 49.95 quantity: 2 multiple: summary: Multiple events (SaaS + custom) value: events: - name: subscription_started user: emails: - jane@example.com data: planName: Pro mrr: 99 - name: newsletter_signup user: emails: - jane@example.com responses: '200': description: Events accepted. `success` is false if any failed to queue. content: application/json: schema: type: object required: - success - eventsIngested properties: success: type: boolean eventsIngested: type: integer description: Number of events queued. example: success: true eventsIngested: 1 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' components: responses: BadRequest: description: Validation error. Includes an `errors` array with per-field detail. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: >- Missing or invalid `x-api-key` / `x-pixel-id`, or key is revoked/expired. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- API key does not carry the required scope for this endpoint, or body `pixelId` does not match the `x-pixel-id` header. content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Error: type: object required: - message properties: message: type: string description: Human-readable error message. errors: type: array description: Per-field validation errors (present on 400 responses). items: type: object properties: message: type: string key: type: string path: type: array items: type: string securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Your Upstack API key. Starts with `upstack_`. pixelId: type: apiKey in: header name: x-pixel-id description: The pixel id the request targets. ````