Ninetailed Events API
Batch event ingestion endpoints for profile enrichment.
OpenAPI Specification
openapi: 3.0.1
info:
title: Ninetailed Experience Events API
description: The core REST API for the Ninetailed (now Contentful Personalization) platform. Returns visitor profiles and resolves which experience and variant to render based on audience rules. Deployed on the edge for high performance. Supports profile creation, updates, retrieval, deletion, event tracking, and batch event import for audience segmentation and A/B test delivery.
version: '2'
contact:
name: Ninetailed Support
url: https://www.contentful.com/help/
license:
name: Proprietary
servers:
- url: https://experience.ninetailed.co/v2/organizations/{organizationId}/environments/{environmentSlug}
description: Ninetailed Experience API edge endpoint
variables:
organizationId:
description: The organization ID (Client ID) found in the SDK Keys section on the Optimization tab.
default: YOUR_ORGANIZATION_ID
environmentSlug:
description: The environment slug (e.g. "main").
default: main
tags:
- name: Events
description: Batch event ingestion endpoints for profile enrichment.
paths:
/events:
post:
operationId: batchUpsertSync
summary: Batch Upsert Events (Synchronous)
description: Synchronous batch endpoint for upserting events across multiple profiles. Supports up to 200 events total, a maximum of 50 identify events, and up to 50 unique profiles per request. Returns an array of profiles without experiences or changes.
tags:
- Events
parameters:
- $ref: '#/components/parameters/locale'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchEventsRequest'
example:
events:
- type: identify
userId: user-abc
traits:
plan: enterprise
- type: page
userId: user-abc
properties:
url: https://example.com/pricing
path: /pricing
text/plain:
schema:
$ref: '#/components/schemas/BatchEventsRequest'
responses:
'200':
description: Events processed; returns array of updated profiles.
content:
application/json:
schema:
$ref: '#/components/schemas/BatchEventsResponse'
'400':
$ref: '#/components/responses/BadRequest'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
/import/events:
post:
operationId: batchUpsertAsync
summary: Batch Upsert Events (Asynchronous)
description: Asynchronous fire-and-forget batch endpoint for importing events. Returns 200 immediately without waiting for processing. Ideal for high-volume imports where response data is not needed.
tags:
- Events
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchEventsRequest'
text/plain:
schema:
$ref: '#/components/schemas/BatchEventsRequest'
responses:
'200':
description: Request accepted for asynchronous processing.
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncConfirmation'
'400':
$ref: '#/components/responses/BadRequest'
'500':
$ref: '#/components/responses/InternalServerError'
components:
parameters:
locale:
name: locale
in: query
required: false
description: BCP 47 locale string used for resolving localized experiences. Defaults to "en".
schema:
type: string
default: en
example: en-US
schemas:
Session:
type: object
description: Session-level metadata for the visitor.
properties:
id:
type: string
description: Unique session identifier.
isReturningVisitor:
type: boolean
description: True if the visitor has been seen in a previous session.
landingPage:
type: string
description: URL of the first page visited in this session.
count:
type: integer
description: Number of sessions this visitor has had.
sessionLength:
type: integer
description: Length of the current session in seconds.
Location:
type: object
description: Geographic location resolved from the visitor's IP address.
properties:
lat:
type: number
format: double
description: Latitude coordinate.
lon:
type: number
format: double
description: Longitude coordinate.
city:
type: string
description: City name.
region:
type: string
description: Region or state code.
country:
type: string
description: ISO 3166-1 alpha-2 country code.
timezone:
type: string
description: IANA timezone identifier (e.g. "America/New_York").
AsyncConfirmation:
type: object
description: Confirmation that an asynchronous import request was accepted.
properties:
data:
type: object
description: Empty object; processing happens asynchronously.
error:
type: object
nullable: true
message:
type: string
example: ok
BatchEventsResponse:
type: object
description: Response envelope for synchronous batch events, containing profile updates without experiences.
properties:
data:
type: array
description: Array of updated profiles.
items:
$ref: '#/components/schemas/Profile'
error:
type: object
nullable: true
message:
type: string
example: ok
Profile:
type: object
description: A visitor profile containing identity, behavioral, and session data used for personalization.
properties:
id:
type: string
description: Unique identifier for the visitor profile.
stableId:
type: string
description: Stable cross-session identifier for the visitor.
random:
type: number
format: double
minimum: 0
maximum: 1
description: Random value (0-1) used for traffic splitting in A/B tests.
audiences:
type: array
description: List of audience IDs the visitor currently qualifies for.
items:
type: string
traits:
type: object
additionalProperties: true
description: Merged identify traits for the visitor.
location:
$ref: '#/components/schemas/Location'
session:
$ref: '#/components/schemas/Session'
jurisdiction:
type: string
description: Regulatory jurisdiction code (e.g. "GDPR") resolved from location.
stickyVariants:
type: object
additionalProperties:
type: string
description: Map of experience ID to variant index for sticky (consistent) assignment.
BatchEventsRequest:
type: object
required:
- events
description: Request body for batch event ingestion. Maximum 200 events, 50 identify events, 50 unique profiles per request.
properties:
events:
type: array
maxItems: 200
description: Array of events to ingest across multiple profiles.
items:
$ref: '#/components/schemas/Event'
ApiError:
type: object
description: Error response envelope.
required:
- message
- error
properties:
message:
type: string
description: Human-readable error message.
data:
type: object
description: Empty object on error.
error:
type: object
description: Structured error details.
properties:
code:
type: string
enum:
- ERR_INVALID_DATA
- ERR_CONFIG_NOT_FOUND
- ERR_PROFILE_NOT_FOUND
- ERR_NAMESPACE_MISMATCH
- ERR_PROFILE_OVERLOAD
- ERR_INTERNAL_SERVER_ERROR
description: Machine-readable error code.
Event:
type: object
required:
- type
description: A behavioral or identity event associated with a visitor profile.
properties:
type:
type: string
enum:
- page
- track
- identify
- screen
- component
description: The type of event being recorded.
userId:
type: string
description: Stable user identifier for linking anonymous and identified sessions.
anonymousId:
type: string
description: Anonymous identifier for unidentified visitors.
name:
type: string
description: Name of the page, screen, or track event.
traits:
type: object
additionalProperties: true
description: Key-value pairs describing user attributes (used with identify events).
properties:
type: object
additionalProperties: true
description: Key-value pairs describing event properties (used with page/track events).
properties:
url:
type: string
format: uri
description: Full URL of the page.
path:
type: string
description: Path portion of the URL.
title:
type: string
description: Page title.
referrer:
type: string
format: uri
description: Referring URL.
timestamp:
type: string
format: date-time
description: ISO 8601 timestamp of when the event occurred.
responses:
BadRequest:
description: Invalid request data.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
message: Invalid data provided
data: {}
error:
code: ERR_INVALID_DATA
TooManyRequests:
description: Profile has exceeded the allowed number of concurrent requests.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
message: Profile overload
data: {}
error:
code: ERR_PROFILE_OVERLOAD
InternalServerError:
description: An unexpected server error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
message: Internal server error
data: {}
error:
code: ERR_INTERNAL_SERVER_ERROR