Lytics Subscription API
**BETA API** Subscriptions are queries into real-time events in Lytics, most commonly listening to a list of users entering/leaving segments ie _triggers_. **Common Use Cases** * Upon Entering/Leaving you want to send a notification callback with that user data so you can email them, save it, etc. * Upon Entering Segment, get notified, save an update to a local user-profile so next time they log in, used in your app. * Upon Entering Segments, get updated with many segments user is member of, and update list of messages user will see next time they logon to app. **Channels** Types of streams the event can be delivered. * *Webhooks* * *AWS Kinesis* * *Azure Event-Hub* * *??? Ask us* Google PubSub. Some features: * *withbackfill* this true/false flag to indicate whether to backfill webhook events for users currently a member of a segment. Default is false, so only new users entering/exiting a segment would cause a webhook. If you enter withbackfill=true then all users currently a member of the segment at time of submission would have a webhook fired for them as well, then changes going forward would start firing. If backfill is used, only a single segment can be specified. **Example** ``` export LIOKEY="your_api_key" export LIODATAKEY="your_data_key" # UPSERT Segment uses "ALIAS" as id for create/update curl -s -H "Authorization: $LIOKEY" -H "Content-Type: text/plain" \ -XPOST "https://api.lytics.io/api/segment" -d ' -- Paying Users Segment FILTER AND ( paying_user = "t" ) FROM user ALIAS demo_segment ' | jq '.' # get that Segment ID SEGID=`curl -s "https://api.lytics.io/api/segment?key=$LIOKEY" | jq -r '.data[] | select(.name == "demo_segment") | .id'` echo "Created Segment id=$SEGID" # Create Webhook Subscription to send entry/exits events to your url # - entry/exits will be sent to the ngrok url below (create your own) # - we use app-engine for this echo ' { "webhook_url": "http://123456abc.ngrok.com/" , "segment_ids": ["1234abcd"] , "withbackfill": false , "channel" : "webhook" , "name" : "webhooktest1" , "description": "What is this subscription for?" } ' | \ curl -v -XPOST "https://api.lytics.io/api/subscription" \ -H "Authorization: $LIOKEY" \ -H "Content-Type: application/json" -d @- | jq '.' # for kinesis curl -s -H "Authorization: $LIOKEY" -H "Content-Type: application/json" \ -XPOST "https://api.lytics.io/api/subscription" -d ' { "channel":"kinesis", "segment_ids": ["1234abcd","abc345"], "name":"test2", "description":"hello world", "stream":"lytics_triggers_stream", "region": "us-east-1", "identifier_field":"user_id", "role_arn":"arn:aws:iam::4444444444444:role/LyticsWriteToKinesis" } ' | jq "." # send test data ... # toggling these next two should move user in/out of segment causing trigger curl -s -XPOST "https://api.lytics.io/collect/json/demo" -H "Authorization: $LIODATAKEY" -H 'Content-type: application/json' \ -d '{ "paying_user":"f", "user_id":"user123"}' | jq '.' curl -s -XPOST "https://api.lytics.io/collect/json/demo" -H "Authorization: $LIODATAKEY" -H 'Content-type: application/json' \ -d '{ "paying_user":"t", "user_id":"user123"}' | jq '.' ``` **Webhook Post Example** This will send a json document like below to your subscription channel. But, this is a **BETA API** and this will change. We received feedback that the more logical set of data is all segment changes (not just one per subscription) so we are modifying the response to be an array of segment entry/exits. ## Example Message There are still message format from v1 of this api to maintain backwards compatibility. ``` { "data": { "_created": "2016-06-29T18:50:16.902758229Z", "_modified": "2017-03-18T06:12:36.829070108Z", "email": "testwebhook@lytics.io", "user_id": "user123", "segment_events":[ { "id": "d3d8f15855b6b067709577342fe72db9", "event": "exit", "enter": "2017-03-02T06:12:36.829070108Z", "exit": "2017-03-18T06:12:36.829070108Z", "slug": "demo_segment" }, { "id": "abc678asdf", "event": "enter", "enter": "2017-03-02T06:12:36.829070108Z", "exit": "2099-03-18T06:12:36.829070108Z", "slug": "another_segment" } ] }, "meta":{ "object":"user", "source":"subscription", "subscription_id": "7e2b8804bbe162cd3f9c0c5991bf3078" } } ```
GET
/api/subscription
SubscriptionList
#
POST
/api/subscription
Subscription Upsert
#
GET
/api/subscription/{id}
Subscription Fetch
#
DELETE
/api/subscription/{id}
Subscription Delete
#
Documentation
Specifications
Other Resources
Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: V1 Lytics Subscription API
version: 1.0.0
description: "The Lytics API is a _restful_ *JSON* api that includes:\n* *Data Collection* api's for collection, and upload of custom data.\n* *Personalization api* for real-time user profile usage in personalization.\n* *Segmentation api* for lists of users, and creating/managing the segmentation rules.\n* *Catalog api* for schema information.\n* *Content api* for content recommendation, and content-classification to drive personalization.\n* *Management api* for general account management.\n## Authentication\nThe *Lytics API* supports authentication using one of the following:\nLogin to your account [Lytics App](https://activate.getlytics.com) and navigate to *Account* to find your keys.\nAfter you have acquired your token, use it to access the Lytics API.\nOur api supports two methods for authorization:\n* query string url parameter, using **access_token**\n* http **Authorization** HEADER\n\n```\n# example showing passing auth token in header\ncurl -XPOST 'https://api.lytics.io/api/segment' \\\n -H \"Authorization: pretendtoken8762\" \\\n -H 'Content-type: application/json' \\\n -d '{\"notreal\" : []}'\n\n# example as query string parameter\ncurl -XPOST 'https://api.lytics.io/api/segment?access_token=804ef78pretendtoken8762' \\\n -H 'Content-type: application/json' \\\n -d '{\"notreal\" : []}'\n\n```\n\nAdditionally, there are two types of authentication token's:\n\n* *User Auth Token* is normally just for the web admin. But may be used on the api, this is a user-specific token, and attributes actions to this user. This token expires.\n\n* *API User* is a less privileged role and does not expire. But, less history is available on actions.\n\n## IP Whitelisting\n\nFor better security, you can manage access to the Lytics API using the IP address whitelisting api_ip_whitelist setting on your account. This setting will also be applied to manage admin access to your Lytics account.\n\nProvide a CIDR value for the range of IP addresses you trust. Lytics will then ignore any unauthenticated users and/or IP addresses that fall out of the valid range. This means you can grant access to only your trusted users.\n\nWhat is CIDR?\nCIDR is a flexible allocation of IP addresses. Use an [IP address tool] (https://www.ipaddressguide.com/), to convert your IP addresses into a CIDR format, either v4 or v6.\n\n## Documentation Examples\n\nWe use [jq json command line prettifier](https://stedolan.github.io/jq/) in our examples throughout this doc.\n\n## Media Types\n\nOur API is a JSON REST API. We have data-upload api's which support\ncsv uploads as well.\n\nRequests with a message-body use plain JSON to set or update resource states.\n\n## Error States\n\nThe common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used.\n\n## Query Parameters\n\nA variety of places our api accepts query parameters that allow a list of values.\nThe documentation will often say it allows `[]string or []int` (meaning an array of strings, or integers).\nWhen this occurs, we allow a variety of formats to pass these.\n\n* `ids=1234` convert this to []string{\"123\"}\n\n* `ids=[123,456]` convert this to []string{\"123\",\"456\"}\n\n* `ids=123,456` convert this to []string{\"123\",\"456\"}\n\n* `ids=123&ids=456` convert this to []string{\"123\",\"456\"}\n\n* `ids[]=123&ids[]=456` convert this to []string{\"123\",\"456\"} Note that we alias ids[] = ids"
servers:
- url: https://api.lytics.io
tags:
- name: Subscription
description: "**BETA API**\n\nSubscriptions are queries into real-time events in Lytics, most\ncommonly listening to a list of users entering/leaving segments\nie _triggers_.\n\n**Common Use Cases**\n\n* Upon Entering/Leaving you want to send a notification callback with that user data so you can email them, save it, etc.\n\n* Upon Entering Segment, get notified, save an update to a local user-profile so next time they log in, used in your app.\n\n* Upon Entering Segments, get updated with many segments user is member of, and update list of messages user will see next time they logon to app.\n\n**Channels**\nTypes of streams the event can be delivered.\n\n* *Webhooks*\n\n* *AWS Kinesis*\n\n* *Azure Event-Hub*\n\n* *??? Ask us* Google PubSub.\n\nSome features:\n\n* *withbackfill* this true/false flag to indicate whether to backfill webhook events\n for users currently a member of a segment. Default is false, so only new users\n entering/exiting a segment would cause a webhook. If you enter withbackfill=true\n then all users currently a member of the segment at time of submission would have\n a webhook fired for them as well, then changes going forward would start firing.\n If backfill is used, only a single segment can be specified.\n\n**Example**\n\n```\nexport LIOKEY=\"your_api_key\"\nexport LIODATAKEY=\"your_data_key\"\n\n# UPSERT Segment uses \"ALIAS\" as id for create/update\ncurl -s -H \"Authorization: $LIOKEY\" -H \"Content-Type: text/plain\" \\\n -XPOST \"https://api.lytics.io/api/segment\" -d '\n\n-- Paying Users Segment\nFILTER AND (\n paying_user = \"t\"\n)\nFROM user\nALIAS demo_segment\n\n' | jq '.'\n\n# get that Segment ID\nSEGID=`curl -s \"https://api.lytics.io/api/segment?key=$LIOKEY\" | jq -r '.data[] | select(.name == \"demo_segment\") | .id'`\necho \"Created Segment id=$SEGID\"\n\n# Create Webhook Subscription to send entry/exits events to your url\n# - entry/exits will be sent to the ngrok url below (create your own)\n# - we use app-engine for this\necho '\n{\n \"webhook_url\": \"http://123456abc.ngrok.com/\"\n , \"segment_ids\": [\"1234abcd\"]\n , \"withbackfill\": false\n , \"channel\" : \"webhook\"\n , \"name\" : \"webhooktest1\"\n , \"description\": \"What is this subscription for?\"\n}\n' | \\\ncurl -v -XPOST \"https://api.lytics.io/api/subscription\" \\\n -H \"Authorization: $LIOKEY\" \\\n -H \"Content-Type: application/json\" -d @- | jq '.'\n\n# for kinesis\n\ncurl -s -H \"Authorization: $LIOKEY\" -H \"Content-Type: application/json\" \\\n -XPOST \"https://api.lytics.io/api/subscription\" -d '\n{\n \"channel\":\"kinesis\",\n \"segment_ids\": [\"1234abcd\",\"abc345\"],\n \"name\":\"test2\",\n \"description\":\"hello world\",\n \"stream\":\"lytics_triggers_stream\",\n \"region\": \"us-east-1\",\n \"identifier_field\":\"user_id\",\n \"role_arn\":\"arn:aws:iam::4444444444444:role/LyticsWriteToKinesis\"\n}\n' | jq \".\"\n\n# send test data ...\n\n# toggling these next two should move user in/out of segment causing trigger\ncurl -s -XPOST \"https://api.lytics.io/collect/json/demo\" -H \"Authorization: $LIODATAKEY\" -H 'Content-type: application/json' \\\n -d '{ \"paying_user\":\"f\", \"user_id\":\"user123\"}' | jq '.'\n\ncurl -s -XPOST \"https://api.lytics.io/collect/json/demo\" -H \"Authorization: $LIODATAKEY\" -H 'Content-type: application/json' \\\n -d '{ \"paying_user\":\"t\", \"user_id\":\"user123\"}' | jq '.'\n\n```\n\n**Webhook Post Example**\nThis will send a json document like below to your subscription channel.\nBut, this is a **BETA API** and this will change. We\nreceived feedback that the more logical set of data\nis all segment changes (not just one per subscription) so we\nare modifying the response to be an array of segment entry/exits.\n\n## Example Message\n\nThere are still message format from v1 of this api to\nmaintain backwards compatibility.\n\n```\n{\n \"data\": {\n \"_created\": \"2016-06-29T18:50:16.902758229Z\",\n \"_modified\": \"2017-03-18T06:12:36.829070108Z\",\n \"email\": \"testwebhook@lytics.io\",\n \"user_id\": \"user123\",\n \"segment_events\":[\n {\n \"id\": \"d3d8f15855b6b067709577342fe72db9\",\n \"event\": \"exit\",\n \"enter\": \"2017-03-02T06:12:36.829070108Z\",\n \"exit\": \"2017-03-18T06:12:36.829070108Z\",\n \"slug\": \"demo_segment\"\n },\n {\n \"id\": \"abc678asdf\",\n \"event\": \"enter\",\n \"enter\": \"2017-03-02T06:12:36.829070108Z\",\n \"exit\": \"2099-03-18T06:12:36.829070108Z\",\n \"slug\": \"another_segment\"\n }\n ]\n },\n \"meta\":{\n \"object\":\"user\",\n \"source\":\"subscription\",\n \"subscription_id\": \"7e2b8804bbe162cd3f9c0c5991bf3078\"\n }\n}\n```"
paths:
/api/subscription:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionListModel'
examples:
response:
value:
data:
- id: 3573009ab39bbc9614f754c0fafd53d7
segment_ids:
- f897270369f977294871f21cc0d826e7
segmentql: FILTER AND ( score_momentum > 25, score_quantity > 25 ) ALIAS seg_webhook1
description: hello world
name: test1
updated: '2016-06-30T15:33:14.376262062-07:00'
created: '2016-06-30T15:33:14.37626196-07:00'
user_id: 2916b84ba4fa8b510591fd6e1c2320db
account_id: testid
workflow: webhook_triggers
security:
- ApiKeyAuth: []
summary: SubscriptionList
operationId: SubscriptionList
description: "Get A list of all Subscriptions.\n\n```sh\n\n# find subscriptions that contain a specific segment.Id or segment.Slug\ncurl -s -H \"Authorization: $LIOKEY\" -H \"Content-Type: application/json\" \\\n \"https://api.lytics.io/api/subscription?segment_id=seg_webhook1\" | jq \".\"\n\n# same but use id.\ncurl -s -H \"Authorization: $LIOKEY\" -H \"Content-Type: application/json\" \\\n \"https://api.lytics.io/api/subscription?segment_id=f897270369f977294871f21cc0d826e7\" | jq \".\"\n\n```"
tags:
- Subscription
parameters:
- name: account_id
in: query
description: Your Lytics account ID.
required: false
schema:
type: string
- name: segment_id
in: query
description: Id of Segment Id OR Slug to filter on
required: false
schema:
type: string
default: '``'
- name: table
in: query
description: Table name.
required: false
schema:
type: string
default: user
post:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionModel'
examples:
response:
value:
data:
id: 3573009ab39bbc9614f754c0fafd53d7
segment_ids:
- f897270369f977294871f21cc0d826e7
segmentql: FILTER AND ( score_momentum > 25, score_quantity > 25 ) ALIAS seg_webhook1
description: hello world
name: test1
updated: '2016-06-30T15:33:14.376262062-07:00'
created: '2016-06-30T15:33:14.37626196-07:00'
user_id: 2916b84ba4fa8b510591fd6e1c2320db
account_id: testid
workflow: webhook_triggers
security:
- ApiKeyAuth: []
summary: Subscription Upsert
operationId: Subscription Upsert
description: "Upsert a new Subscription. Subscriptions allow you to listen and recieve\nnotification of events inside of Lytics, most common would be listen\nto users entering/leaving segments to serve as triggers.\n\nWhen creating subscriptions they have the following fields.\n\n| field | DataType | Description |\n|---------------|------------------|---------------|\n| channel | string | Required: What Type of subscription. [kinesis, webhook]\n| name | string | Name of this Subscription\n| description | string | Long text description (optional)\n| segment_ids | []string | List of segment Ids\n| withbackfill | bool | Should all members of this segment be included? They will be marked as \"entered\" segment.\n\n*Webhook* only fields:\n\n| field | DataType | Description |\n|---------------|-------------------|---------------|\n| webhook_url | string | Required for Webhooks, only used on webhooks, url to post to.\n| headers | map[string]string | Optional map of headers to send with webhook\n| segmentio_writekey | string | Optional api key for sending to segment.io\n\n*Kinesis* only fields:\n\n| field | DataType | Description |\n|------------------|------------------|---------------|\n| region | string | Required. AWS Region\n| stream | string | Required. Kinesis stream\n| role_arn | string | AWS IAM Role to use for assume-role (see integrations doc)\n| identifier_field | string | Optional. If provided, pull this field from user field and use as shard-key in Kinesis Put.\n\nCreate a Webhook Subscription that includes the Segment definition and custom headers (optional)\n\n```sh\n\ncurl -s -H \"Authorization: $LIOKEY\" -H \"Content-Type: application/json\" \\\n -XPOST \"https://api.lytics.io/api/subscription\" -d '\n{\n \"segmentql\": \"FILTER AND ( score_momentum > 25, score_quantity > 25 ) ALIAS seg_webhook1\",\n \"name\":\"test1\",\n \"channel\" : \"webhook\",\n \"description\":\"hello world\",\n \"webhook_url\":\"https://demo.appspot.com/log\",\n \"headers\": {\"Authorization\": \"dGhpczp0aGF0\"}\n}\n' | jq \".\"\n```\n\nCreate a Webhook subscription with list of SegmentId's (previously created)\nto listen to.\n\n```\ncurl -s -H \"Authorization: $LIOKEY\" -H \"Content-Type: application/json\" \\\n -XPOST \"https://api.lytics.io/api/subscription\" -d '\n{\n \"segment_ids\": [\"1234abcd\",\"abc345\"],\n \"channel\":\"webhook\",\n \"name\":\"test2\",\n \"description\":\"hello world\",\n \"webhook_url\":\"https://demo.appspot.com/log\"\n}\n' | jq \".\"\n\n```\n\nCreate a Kinesis Subscription\n\n```\n\ncurl -s -H \"Authorization: $LIOKEY\" -H \"Content-Type: application/json\" \\\n -XPOST \"https://api.lytics.io/api/subscription\" -d '\n{\n \"channel\":\"kinesis\",\n \"segment_ids\": [\"1234abcd\",\"abc345\"],\n \"name\":\"test2\",\n \"description\":\"hello world\",\n \"stream\":\"lytics_triggers_stream\",\n \"region\": \"us-east-1\",\n \"identifier_field\":\"user_id\",\n \"role_arn\":\"arn:aws:iam::4444444444444:role/LyticsWriteToKinesis\"\n}\n' | jq \".\"\n\n\n\n```"
tags:
- Subscription
parameters:
- name: account_id
in: query
description: Your Lytics account ID.
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
segment_ids:
type: array
items:
type: string
name:
type: string
channel:
type: string
withbackfill:
type: boolean
description:
type: string
webhook_url:
type: string
example:
segment_ids:
- 1234abcd
- abc345
name: test2
channel: webhook
withbackfill: false
description: hello world
webhook_url: https://lyticswwwapp.appspot.com/log
/api/subscription/{id}:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionModel'
examples:
response:
value:
data:
id: 3573009ab39bbc9614f754c0fafd53d7
segment_ids:
- f897270369f977294871f21cc0d826e7
segmentql: FILTER AND ( score_momentum > 25, score_quantity > 25 ) ALIAS seg_webhook1
description: hello world
name: test1
updated: '2016-06-30T15:33:14.376262062-07:00'
created: '2016-06-30T15:33:14.37626196-07:00'
user_id: 2916b84ba4fa8b510591fd6e1c2320db
account_id: testid
workflow: webhook_triggers
security:
- ApiKeyAuth: []
summary: Subscription Fetch
operationId: Subscription Fetch
description: Get a single Subscription Webhook.
tags:
- Subscription
parameters:
- name: account_id
in: query
description: Your Lytics account ID.
required: false
schema:
type: string
- name: id
in: path
description: subscription Id in path
required: true
example: '1234'
schema:
type: string
delete:
responses:
'204':
description: No Content
headers: {}
security:
- ApiKeyAuth: []
summary: Subscription Delete
operationId: Subscription Delete
description: Delete A Subscription.
tags:
- Subscription
parameters:
- name: account_id
in: query
description: Your Lytics account ID.
required: false
schema:
type: string
- name: id
in: path
description: subscription Id in path
required: true
example: '1234'
schema:
type: string
components:
schemas:
SubscriptionListModel:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
segment_ids:
type: array
items:
type: string
segmentql:
type: string
description:
type: string
name:
type: string
updated:
type: string
created:
type: string
user_id:
type: string
account_id:
type: string
workflow:
type: string
example:
data:
- id: 3573009ab39bbc9614f754c0fafd53d7
segment_ids:
- f897270369f977294871f21cc0d826e7
segmentql: FILTER AND ( score_momentum > 25, score_quantity > 25 ) ALIAS seg_webhook1
description: hello world
name: test1
updated: '2016-06-30T15:33:14.376262062-07:00'
created: '2016-06-30T15:33:14.37626196-07:00'
user_id: 2916b84ba4fa8b510591fd6e1c2320db
account_id: testid
workflow: webhook_triggers
SubscriptionModel:
type: object
properties:
data:
type: object
properties:
id:
type: string
segment_ids:
type: array
items:
type: string
segmentql:
type: string
description:
type: string
name:
type: string
updated:
type: string
created:
type: string
user_id:
type: string
account_id:
type: string
workflow:
type: string
example:
data:
id: 3573009ab39bbc9614f754c0fafd53d7
segment_ids:
- f897270369f977294871f21cc0d826e7
segmentql: FILTER AND ( score_momentum > 25, score_quantity > 25 ) ALIAS seg_webhook1
description: hello world
name: test1
updated: '2016-06-30T15:33:14.376262062-07:00'
created: '2016-06-30T15:33:14.37626196-07:00'
user_id: 2916b84ba4fa8b510591fd6e1c2320db
account_id: testid
workflow: webhook_triggers
securitySchemes:
ApiKeyAuth:
in: header
name: Authorization
type: apiKey
x-readme:
explorer-enabled: true
proxy-enabled: true