Overview
Aampe provides two main APIs that work together to power personalized experiences:| API | Purpose | Base URL |
|---|---|---|
| Content API | Retrieve personalized content for Surfaces | https://content.api.aampe.com |
| Ingestion API | Send user events and properties to Aampe | https://ingestion.{region}.api.aampe.com |
Content API (Surfaces)
The Content API provides programmatic access to retrieve personalized content for your users across different surfaces. This API powers real-time content decisioning based on your configured agents and optimization strategies. Base URL:https://content.api.aampe.com
Authentication: X-API-Key header (Surfaces API key)
Use Cases
- Fetch personalized content for in-app Surfaces
- Get content assignments for a user at a specific surface
- Verify API connection via health endpoint
Ingestion API (Data)
The Ingestion API allows you to send user events and property updates to Aampe in real time. Use it to stream behavioral data and user attributes that power personalization. Base URL:https://ingestion.{region}.api.aampe.com
Regions: us-east1 | europe-west3 | asia-southeast1
Authentication: Authorization: Bearer <Ingestion API Key> header
Use Cases
- Stream user events (clicks, purchases, page views) as they happen
- Update user properties (attributes, traits, preferences)
- Power real-time personalization and audience targeting
Core Concepts
Surfaces
Surfaces represent locations in your application where Aampe can deliver personalized content. Each surface has a unique UUID and associated configuration.Assignments
When you request content for a surface, Aampe returns an assignment — the specific content variant selected for that user at that moment, along with any configured alternates.Contact IDs
Your user identifiers that Aampe uses to personalize content delivery and track performance. Use the same contact IDs when sending events (Ingestion API) and requesting content (Content API).Response Formats
All API responses return JSON. Successful requests return appropriate HTTP status codes along with the requested data.Error Handling
Both APIs use standard HTTP status codes:| Code | Description |
|---|---|
| 200 | Success (Content API) |
| 202 | Accepted (Ingestion API — request queued for processing) |
| 400 | Bad Request |
| 401 | Unauthorized (invalid or missing API key) |
| 422 | Validation Error |
| 429 | Rate Limited |
| 500 | Server Error |
Getting Started
- Get your API keys — Navigate to Integrations > API keys in the Aampe Dashboard
- Choose your API — Use the Surfaces key for Content API, Ingestion key for Ingestion API
- Test your connection — Use the health endpoint for Content API
- Start building — Send events, update properties, and fetch personalized content