canonical: https://jentic.com/apis/lytics.io/lytics

# Lytics API

Jentic publishes the only available OpenAPI specification for Lytics API, keeping it validated and agent-ready. The Lytics API exposes Lytics' customer data platform across 10 endpoints covering entities (user profiles), segments (audience definitions), and streams (data collection). Authentication uses an Authorization header API key. The API supports the core CDP loop: collect events into a stream, scan and read entity profiles, and define and query segments for audience activation.

## For AI agents

Send events to a Lytics stream, look up entity profiles, and create or query audience segments inside the Lytics customer data platform.

## Scope

Does not handle ad delivery, email sending, or campaign creative - use for Lytics customer data ingest, entity lookup, and segment management only.

## Capabilities

- Collect data into a named stream via POST `/collect/json/{streamName}`
- List streams configured in the workspace and inspect a specific stream's metadata
- Look up an entity (user profile) by entity type, field name, and field value
- Scan entities matching a query via POST `/api/entity`
- List, create, get, update, and delete audience segments via `/api/segment` endpoints
- Drive a CDP-style identity, segmentation, and activation flow over a small, focused surface

## Use cases

### Server-side event collection into a CDP

Backend services and analytics pipelines stream events into Lytics via POST `/collect/json/{streamName}` so user activity is captured outside the browser. This is preferred over client-side tags for transaction events, server jobs, and integrations from third-party tools, since it avoids ad-blocking and ensures the event arrives even if the browser tab closes.

Example prompt: POST `/collect/json/web` with a JSON payload containing user_id, event 'order_completed', and order amount.

### Audience segmentation and activation

Marketing teams build segments inside Lytics - for example 'high-intent buyers viewed pricing in last 7 days' - and then activate them downstream into ad networks or email tools. POST `/api/segment` creates a segment, GET `/api/segment` lists existing ones, and PUT `/api/segment/{segmentId}` updates the rules. The structured endpoints make segments diffable in version control or generated by an AI agent from natural-language briefs.

Example prompt: POST `/api/segment` with the rules for 'viewed pricing twice in last 7 days' and confirm the segment is created with a returned segmentId.

### Entity profile lookup for personalisation

Personalisation services look up a single user's Lytics profile in real time before rendering a page or sending an email. GET `/api/entity/{entityType}/{fieldName}/{fieldValue}` returns the profile by an indexed field (such as email or user ID), and POST `/api/entity` scans for entities matching a broader query. This powers next-best-content and dynamic email content decisions.

Example prompt: GET `/api/entity/user/email/jane`@example.com and return the user's segment memberships and last-seen timestamp.

### Agent-driven CDP automation via Jentic

An AI agent is asked 'create a segment for users who viewed our pricing page twice in the last 7 days and tell me how many match'. Jentic stores the Lytics Authorization key in your Jentic One instance and exposes the segment-create and entity-scan operations by intent so the agent can chain segmentation with profile lookups.

Example prompt: Search Jentic for 'create lytics segment', execute POST `/api/segment` with the rules, then call POST `/api/entity` to count matching profiles.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/entity/{entityType}/{fieldName}/{fieldValue}` | Get entity by indexed field |
| POST | `/api/entity` | Scan entities by query |
| GET | `/api/segment` | List segments |
| POST | `/api/segment` | Create segment |
| PUT | `/api/segment/{segmentId}` | Update segment |
| DELETE | `/api/segment/{segmentId}` | Delete segment |
| POST | `/collect/json/{streamName}` | Collect events into a named stream |

## Key resources

- **Entities** — User profile lookup by indexed field and entity scan by query
- **Segments** — Full CRUD on audience segments
- **Streams** — List and inspect data streams
- **Data Collection** — Server-side event ingest endpoint per stream

## Why Jentic

- **Setup:** Wiring the Lytics API by hand means sending its API key on every request and threading it across entity lookup, segment, and event-collection paths. Through Jentic you install once, import the Lytics API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Lytics puts the segment id in the URL path (`/api/segment/{segmentId}`), so a rule can pin your agent to updating one segment and nothing else. You choose the operations it may call, so destructive ones like deleting a segment are not included unless you add them.
- **Credential handling:** Your Lytics key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Lytics segment', 'look up a user profile', or 'send an event to a stream', and Jentic returns the matching Lytics operation with its parameter schema so the agent calls the right endpoint directly.

## Related APIs

- **Segment** — Customer data platform with broad source/destination ecosystem
- **Mixpanel** — Product analytics with cohorts and funnels
- **Amplitude** — Product analytics with behavioural cohorts and experimentation

## FAQ

### Why is there no official OpenAPI spec for Lytics API?

Lytics does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Lytics API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Lytics API use?

The Lytics API uses an Authorization header carrying an API key. Send the key as the Authorization value on every request to api.lytics.io. Through Jentic, the key is stored encrypted in your Jentic One instance and injected per request, so it never enters the agent's prompt.

### Can I create a segment programmatically and count its members?

Yes. POST `/api/segment` creates the segment with the provided rules, GET `/api/segment/{segmentId}` returns its current definition, and POST `/api/entity` can scan for entities matching the rules so you can count members. PUT and DELETE on `/api/segment/{segmentId}` let you keep the segment in lockstep with rule changes.

### What are the rate limits for the Lytics API?

Concrete rate limits are not declared in this spec. Expect per-account limits scaled to your Lytics plan - design clients to back off on 429 responses and prefer batched event payloads over per-event calls into `/collect/json/{streamName}.`

### How do I send events into Lytics through Jentic?

Search Jentic for 'lytics collect event', load POST `/collect/json/{streamName}`, and execute it with the stream name and event payload. Jentic injects the Authorization API key automatically and the event lands in the named stream for segment evaluation.

### Can I limit what my agent is allowed to do with the Lytics API?

Yes. Jentic One is self-hosted by you, so your own rules decide which Lytics operations and credentials the agent may use. Because Lytics puts the segment id in the URL path (`/api/segment/{segmentId}`), a rule can pin the agent to updating a single segment and nothing else. You also choose which operations are exposed, so destructive calls like deleting a segment or scanning entities via POST `/api/entity` are excluded unless you add them.