openapi: 3.1.0 info: title: Amplitude HTTP V2 API description: >- The Amplitude HTTP V2 API enables developers to send event data directly from servers or clients to Amplitude's analytics platform. It supports uploading individual or batched events along with user properties, event properties, and group properties. This API is the primary method for server-side event ingestion and is designed for high-throughput data collection with built-in validation and error reporting. version: '2' contact: name: Amplitude Support url: https://amplitude.com/contact termsOfService: https://amplitude.com/terms externalDocs: description: Amplitude HTTP V2 API Documentation url: https://amplitude.com/docs/apis/analytics/http-v2 servers: - url: https://api2.amplitude.com description: Amplitude US Production Server - url: https://api.eu.amplitude.com description: Amplitude EU Production Server tags: - name: Events description: Event ingestion operations security: [] paths: /2/httpapi: post: operationId: uploadEvents summary: Amplitude Upload Events description: >- Send up to 10 events per request to Amplitude for ingestion. Each event must include either a user_id or device_id, and an event_type. The API validates the request and returns detailed error reporting for any invalid events in the batch. tags: - Events requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UploadRequestBody' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/UploadResponse' examples: uploadEvents200Example: summary: Default uploadEvents 200 response x-microcks-default: true value: code: 100 events_ingested: 100 payload_size_bytes: 100 server_upload_time: 1718153645993 '400': description: Bad request - invalid events or missing required fields content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: uploadEvents400Example: summary: Default uploadEvents 400 response x-microcks-default: true value: code: 100 error: example_value missing_field: example_value events_with_invalid_fields: {} events_with_missing_fields: {} '413': description: Payload too large '429': description: Too many requests - rate limit exceeded x-microcks-operation: delay: 0 dispatcher: FALLBACK components: schemas: UploadRequestBody: type: object required: - api_key - events properties: api_key: type: string description: >- The API key for the Amplitude project to which events will be sent. events: type: array description: >- An array of event objects to upload. Maximum of 10 events per batch is recommended. maxItems: 2000 items: $ref: '#/components/schemas/Event' options: $ref: '#/components/schemas/UploadOptions' UploadOptions: type: object properties: min_id_length: type: integer description: >- Minimum length for user_id and device_id fields. Default is 5. minimum: 1 Event: type: object required: - event_type properties: user_id: type: string description: >- A readable ID specified by you. Must have a minimum length of 5 characters unless overridden. Required unless device_id is present. device_id: type: string description: >- A device-specific identifier. Required unless user_id is present. event_type: type: string description: >- The name of the event being tracked. time: type: integer format: int64 description: >- The timestamp of the event in milliseconds since epoch. If not provided, Amplitude uses the upload time. event_properties: type: object description: >- A dictionary of key-value pairs representing properties of the event. additionalProperties: true user_properties: type: object description: >- A dictionary of key-value pairs representing properties of the user. Supports set, setOnce, add, append, prepend, unset, and remove operations. additionalProperties: true groups: type: object description: >- A dictionary of group type to group name mappings for this event. additionalProperties: true group_properties: type: object description: >- A dictionary of key-value pairs representing properties of the group. additionalProperties: true app_version: type: string description: >- The version of the application sending the event. platform: type: string description: >- The platform of the device sending the event. os_name: type: string description: >- The name of the operating system of the device. os_version: type: string description: >- The version of the operating system of the device. device_brand: type: string description: >- The brand of the device. device_manufacturer: type: string description: >- The manufacturer of the device. device_model: type: string description: >- The model of the device. carrier: type: string description: >- The carrier of the device. country: type: string description: >- The country of the user. region: type: string description: >- The region or state of the user. city: type: string description: >- The city of the user. dma: type: string description: >- The designated market area of the user. language: type: string description: >- The language setting of the user. price: type: number description: >- The price of the item purchased in a revenue event. quantity: type: integer description: >- The quantity of the item purchased in a revenue event. revenue: type: number description: >- The revenue generated by the event. Use negative values for refunds. productId: type: string description: >- The identifier for the product in a revenue event. revenueType: type: string description: >- The type of revenue for the event, such as purchase or refund. location_lat: type: number format: double description: >- The latitude of the user's location. location_lng: type: number format: double description: >- The longitude of the user's location. ip: type: string description: >- The IP address of the user. Use $remote to use the IP address from the upload request. idfa: type: string description: >- The Identifier for Advertiser (iOS). idfv: type: string description: >- The Identifier for Vendor (iOS). adid: type: string description: >- The Google Play Services advertising ID (Android). android_id: type: string description: >- The Android ID (Android). event_id: type: integer description: >- An incrementing counter to distinguish events with identical user_id and timestamps. session_id: type: integer format: int64 description: >- The start time of the session in milliseconds since epoch. Use -1 for events outside a session. insert_id: type: string description: >- A unique identifier for the event used for deduplication. Amplitude deduplicates subsequent events sent with the same insert_id and device_id or user_id within the past 7 days. UploadResponse: type: object properties: code: type: integer description: >- The HTTP status code of the response. example: 200 events_ingested: type: integer description: >- The number of events successfully ingested. payload_size_bytes: type: integer description: >- The size of the request payload in bytes. server_upload_time: type: integer format: int64 description: >- The time the server received the upload in milliseconds since epoch. ErrorResponse: type: object properties: code: type: integer description: >- The HTTP status code of the error. error: type: string description: >- A human-readable error message describing the issue. missing_field: type: string description: >- The name of the required field that is missing, if applicable. events_with_invalid_fields: type: object description: >- A map of field names to arrays of event indices that had invalid values for those fields. additionalProperties: type: array items: type: integer events_with_missing_fields: type: object description: >- A map of field names to arrays of event indices that were missing required fields. additionalProperties: type: array items: type: integer