Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: V1 Lytics Segment API
version: 1.0.0
description: 'The Lytics API is a _restful_ *JSON* api that includes:
* *Data Collection* api''s for collection, and upload of custom data.'
servers:
- url: https://api.lytics.io
tags:
- name: Segment
description: 'Segments are named, logical expressions
of users.'
paths:
/api/segment:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentListModel'
examples:
response:
value:
data:
- id: 7a7f76ff97ad0e3e96c162f74aee8f8f
account_id: 4f7b525bdba058fc096757a6
author_id: user_12345
kind: segment
segment_ql: FILTER AND ( visits > 5, last_visit >= "2015-04-01 00:00:00Z", last_visit < "2015-04-02 00:00:00Z")
created: '2014-08-04T21:18:20.124Z'
updated: '2014-08-04T21:18:20.124Z'
description: Casual users have been active in the last 90 days and show no extreme behavioral patterns.
is_public: true
name: Recent Visits
slug_name: recent_visits
tags:
- email_trigger
security:
- ApiKeyAuth: []
summary: SegmentList
operationId: SegmentList
description: 'Get list of **Segments** . Segments can refer to any Table.
The two main tables you will be working with are *User* and *Content*.
```
# Grab all segments from "user" table
curl "$LIOAPI/api/segment" -s -H "Authorization: $LIOKEY" | jq ''.''
# Grab all "Content Collections" (ney, segments)
curl "$LIOAPI/api/segment?table=content" -s -H "Authorization: $LIOKEY" | jq ''.''
```'
tags:
- Segment
parameters:
- name: account_id
in: query
description: Your Lytics account ID.
required: false
schema:
type: string
- name: table
in: query
description: Table for segments to fetch, "user" by default, specify "content" for content collections (aka segments).
required: false
example: user
schema:
type: string
- name: valid
in: query
description: True, False or "all". Get all segments, only valid, or only invalid.
required: false
example: all
schema:
type: string
post:
responses:
'201':
description: Created
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentModel'
examples:
response:
value:
data:
id: 7a7f76ff97ad0e3e96c162f74aee8f8f
account_id: 4f7b525bdba058fc096757a6
author_id: 4f7b525bdba058fc096757a6
kind: segment
segment_ql: FILTER AND ( visits > 5, last_visit >= "2015-04-01 00:00:00Z", last_visit < "2015-04-02 00:00:00Z")
created: '2014-08-04T21:18:20.124Z'
updated: '2014-08-04T21:18:20.124Z'
description: Casual users have been active in the last 90 days and show no extreme behavioral patterns.
name: Recent Visits
slug_name: recent_visits
tags:
- email_trigger
security:
- ApiKeyAuth: []
summary: Segment Create
operationId: SegmentCreate
description: 'Create A segment. See **/api/segment/validate**
method for testing out Segmentation rules.
Pass a **Segment QL** logic expression to create
a Segment.
```
# Plain Text api will extract the "our_test_activelist" as the "slug" and "name" of
# the segment
curl -s -XPOST "https://api.lytics.io/api/segment" \
-H "Content-type: text/plain" \
-H "Authorization: $LIOKEY" \
-d''
FILTER AND (
visits > 5,
last_visit >= "now-30d",
scores.momentum > 10
)
ALIAS our_test_activelist
'' | jq ''.''
# or try managing segments in files so you can check them in
# to Bitbucket or Github. Also addresses field-
curl -s -XPOST ''https://api.lytics.io/api/segment'' \
-H ''Content-type: text/plain'' \
-H "Authorization: your_api_token" \
-d @my_segment.json | jq ''.''
# Json Api Allows a few more fields such as description
curl -s -XPOST "https://api.lytics.io/api/segment" \
-H "Authorization: $LIOKEY" \
-H "Content-type: application/json" \
-d''
{
"name":"Most Active Users",
"segment_ql": "FILTER AND (visits > 5,last_visit >= \"now-30d\", scores.momentum > 10)",
"slug_name":"our_test_activelist",
"is_public": true,
"description":"a description of what this is for",
"tags":["email_personalization","product"]
}
'' | jq ''.''
# create a json file of a segment
curl -s -XPOST "$LIOAPI/api/segment" \
-H "Authorization: $LIOKEY" \
-H "Content-type: application/json" \
-d @segment.json | jq ''.''
# Content Collection (ney, "Segment")
curl -s -XPOST "https://api.lytics.io/api/segment" \
-H "Content-type: text/plain" \
-H "Authorization: $LIOKEY" \
-d''
FILTER AND (
EXISTS imageurls -- Make sure they have images
aspects = "article" -- Ensure they are of type article
PATH = "blog" -- only show those from the /blog part of site
created > "now-30d" -- only those authored in last 30 days
)
FROM content
WITH
name = "Recent Blog Articles With Images"
ALIAS recent_blog_articles
'' | jq ''.''
```
SegmentQL
=============================
The query language for segments
```
Filter = "FILTER" Phrase [FROM] [ALIAS]
Phrase = AND | OR | Expression
AND = "AND" (Phrase, Phrase, ...)
OR = "OR" (Phrase, Phrase, ...)
Expression = NOT
| Comparison
| EXISTS
| IN
| CONTAINS
| LIKE
| IncludeSegment
NOT = "NOT" Phrase
Comparison = Identifier ComparisonOp Literal
ComparisonOp = ">" | ">=" | " 1 AND scores.quantity > 20 ) ALIAS multi_channel_active
# Filters can references to other Filters
FILTER AND (
EXISTS email,
NOT INCLUDE multi_channel_active
)
FILTER AND (
visits > 5,
NOT INCLUDE someotherfilter,
)
# negation
FILTER NOT AND ( ... )
# Compound filter
FILTER AND (
visits > 5,
last_visit >= "2015-04-01 00:00:00Z",
last_visit "now-24h"
# IN
city IN ("Portland, OR", "Seattle, WA", "Newark, NJ")
# Complex
AND (
OR (
foo == true
bar != 5
)
EXISTS signup_date
OR (
NOT bar IN (1, 2, 4, 5)
INCLUDE SomeOtherFilter
)
)
# Time Windows
# Can only be used on timebucket fields
# Answers the question "at least X in Y days", where X can be one of (1, 5, 10, 25, 50, 100)
# and Y can be one of (7, 30) days.
#
# timewindow(fieldname, X, Y)
FILTER timewindow(bucketfield, 5, 7)
# Between
FILTER AND (
_modified BETWEEN "2015-07-01" AND "2016-08-01"
)
```'
tags:
- Segment
x-operation-id-source: normalized
x-operation-id-original: Segment Create
/api/segment/{id}:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentModel'
examples:
response:
value:
data:
id: 7a7f76ff97ad0e3e96c162f74aee8f8f
account_id: 4f7b525bdba058fc096757a6
author_id: 4f7b525bdba058fc096757a6
kind: segment
segment_ql: FILTER AND ( visits > 5, last_visit >= "2015-04-01 00:00:00Z", last_visit < "2015-04-02 00:00:00Z")
created: '2014-08-04T21:18:20.124Z'
updated: '2014-08-04T21:18:20.124Z'
description: Casual users have been active in the last 90 days and show no extreme behavioral patterns.
name: Recent Visits
slug_name: recent_visits
tags:
- email_trigger
security:
- ApiKeyAuth: []
summary: Segment Fetch
operationId: SegmentFetch
description: Fetch a segment by **id** or **slug**
tags:
- Segment
parameters:
- name: account_id
in: query
description: Your Lytics account ID.
required: false
schema:
type: string
- name: id
in: path
description: id, or slug of a segment, part of url path
required: true
example: my_segment_slug
schema:
type: string
x-operation-id-source: normalized
x-operation-id-original: Segment Fetch
put:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentModel'
examples:
response:
value:
data:
id: 7a7f76ff97ad0e3e96c162f74aee8f8f
account_id: 4f7b525bdba058fc096757a6
author_id: 4f7b525bdba058fc096757a6
kind: segment
segment_ql: FILTER AND ( visits > 5, last_visit >= "2015-04-01 00:00:00Z", last_visit < "2015-04-02 00:00:00Z")
created: '2014-08-04T21:18:20.124Z'
updated: '2014-08-04T21:18:20.124Z'
description: Casual users have been active in the last 90 days and show no extreme behavioral patterns.
name: Recent Visits
slug_name: recent_visits
tags:
- email_trigger
security:
- ApiKeyAuth: []
summary: Segment Update
operationId: SegmentUpdate
description: 'Update A segment.
```
# You can upsert (insert if new, update if exists)
# by POSTing to api and the ALIAS will be used to lookup
# the existing one and update it.
curl -s -XPOST "https://api.lytics.io/api/segment" \
-H "Content-type: text/plain" \
-H "Authorization: $LIOKEY" \
-d''
FILTER AND (
visits > 5,
last_visit >= "now-30d",
scores.momentum > 10
)
ALIAS our_test_activelist
'' | jq ''.''
# Json Api Allows a few more fields such as description
curl -s -XPUT "https://api.lytics.io/api/segment/123456id" \
-H "Authorization: $LIOKEY" \
-H "Content-type: application/json" \
-d''
{
"name":"Most Active Users",
"segment_ql": "FILTER AND (visits > 5,last_visit >= \"now-30d\", scores.momentum > 10)",
"slug_name":"our_test_activelist",
"is_public": true,
"description":"a description of what this is for"
}
'' | jq ''.''
```'
tags:
- Segment
parameters:
- name: account_id
in: query
description: Your Lytics account ID.
required: false
schema:
type: string
- name: id
in: path
description: id, or slug of a segment, part of url path
required: true
example: my_segment_slug
schema:
type: string
x-operation-id-source: normalized
x-operation-id-original: Segment Update
delete:
responses:
'204':
description: No Content
headers: {}
security:
- ApiKeyAuth: []
summary: Segment Delete
operationId: SegmentDelete
description: Delete A segment.
tags:
- Segment
parameters:
- name: account_id
in: query
description: Your Lytics account ID.
required: false
schema:
type: string
- name: id
in: path
description: id, or slug of a segment, part of url path
required: true
example: my_segment_slug
schema:
type: string
x-operation-id-source: normalized
x-operation-id-original: Segment Delete
/api/segment/size:
post:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentSizeModel'
examples:
response:
value:
data:
id: ''
name: active
slug_name: active
size: 10402
security:
- ApiKeyAuth: []
summary: SegmentSize
operationId: SegmentSize
description: 'Get size of a single Segment using SegmentQL, not saved.
This api is very rate throttled, 1/10 seconds.
```
# Post a SegmentQL query to size api to fetch size
curl -s -XPOST "https://api.lytics.io/api/segment/size" \
-H "Content-type: text/plain" \
-H "Authorization: your_api_token" \
-d''
FILTER AND (
visits > 5,
last_visit >= "now-30d",
scores.momentum > 10
)
'' | jq ''.''
```'
tags:
- Segment
/api/segment/validate:
post:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentValidateModel'
examples:
response:
value:
status: 200
message: success
data: null
security:
- ApiKeyAuth: []
summary: SegmentValidate
operationId: SegmentValidate
description: Validate single Segment Query Statement
tags:
- Segment
/api/segment/sizes:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentSizesModel'
examples:
response:
value:
data:
- id: 456dert
name: Active
slug_name: active
size: 10402
- id: 1234abcd
type: custom
slug_name: active
size: 45236
security:
- ApiKeyAuth: []
summary: SegmentSizes
operationId: SegmentSizes
description: Get bunch of segment sizes.
tags:
- Segment
parameters:
- name: account_id
in: query
description: Your Lytics account ID.
required: false
schema:
type: string
- name: ids
in: query
description: list of ids to get, format = ids[]=123&ids[]=234 OR ids=123,345 etc, see standard []string param doc
required: true
example: 123,456
schema:
type: string
/api/segment/{segId}/scan:
get:
responses:
'200':
description: OK
headers: {}
content:
'*/*':
schema:
$ref: '#/components/schemas/SegmentScanModel'
security:
- ApiKeyAuth: []
summary: SegmentScan
operationId: SegmentScan
description: Get a paged list of **Users** for a **Segment**.
tags:
- Segment
parameters:
- name: account_id
in: query
description: Your Lytics account ID.
required: false
schema:
type: string
- name: segId
in: path
description: segment Id in path
required: true
example: '1234'
schema:
type: string
- name: id
in: query
description: segment Id in querystring instead of path then use `api/segment/scan`
required: false
example: '1234'
schema:
type: string
- name: limit
in: query
description: num of rows to return per call, default = 10, max = 100
required: false
example: '10'
schema:
type: integer
- name: splits
in: query
description: 1,2,3 comma seperated list of ints 0-99 for a-b split testing (a=1,5,8 )
required: false
example: 1,2,3
schema:
type: string
- name: start
in: query
description: optional ID of a previous segment scan to resume, must be recent this is retrieved from the `next` parameter in JSON response
required: false
example: next_xyz
schema:
type: integer
- name: meta
in: query
description: optional boolean, whether to include schema in response
required: false
example: 'true'
schema:
type: boolean
- name: sortfield
in: query
description: field to sort on
required: false
example: last_visit_ts
schema:
type: string
- name: sortorder
in: query
description: '[desc,asc]'
required: false
example: '20'
schema:
type: string
- name: recent
in: query
description: short cut for last visit timestamp desc [t,true,]
required: false
example: 'true'
schema:
type: boolean
- name: segments
in: query
description: JSON of ad-hoc segment, or pass this in http Body
required: false
example: '{rules...}'
schema:
type: string
- name: fields
in: query
description: list of fields to include in response
required: false
example: email,user_id,name
schema:
type: string
delete:
responses:
'204':
description: No Content
headers: {}
security:
- ApiKeyAuth: []
summary: Segment Batch Delete
operationId: SegmentBatchDelete
description: 'Delete a Batch of segments
```
# ids=1234 convert this to []string{"123"}
# ids=[123,456] convert this to []string{"123","456"}
# ids=123,456 convert this to []string{"123","456"}
# ids=123&ids=456 convert this to []string{"123","456"}
# ids[]=123&ids[]=456 convert this to []string{"123","456"} Note that we alias ids[] = ids
curl -s -XDELETE -H "Content-Type: application/json" \
- H "Authorization: $LIOKEY" \
"https://api.lytics.io/api/segment?ids=21decdea54052ea1285478ecac53d1ed,59e39389fbf738d75246749a6146d280" \
| jq ''.''
```'
tags:
- Segment
parameters:
- name: account_id
in: query
description: Your Lytics account ID.
required: false
schema:
type: string
- name: segId
in: path
description: segment Id in path
required: true
example: '1234'
schema:
type: string
- name: id
in: query
description: segment Id in querystring instead of path then use `api/segment/scan`
required: false
example: '1234'
schema:
type: string
- name: limit
in: query
description: num of rows to return per call, default = 10, max = 100
required: false
example: '10'
schema:
type: integer
- name: splits
in: query
description: 1,2,3 comma seperated list of ints 0-99 for a-b split testing (a=1,5,8 )
required: false
example: 1,2,3
schema:
type: string
- name: start
in: query
description: optional ID of a previous segment scan to resume, must be recent this is retrieved from the `next` parameter in JSON response
required: false
example: next_xyz
schema:
type: integer
- name: meta
in: query
description: optional boolean, whether to include schema in response
required: false
example: 'true'
schema:
type: boolean
- name: sortfield
in: query
description: field to sort on
required: false
example: last_visit_ts
schema:
type: string
- name: sortorder
in: query
description: '[desc,asc]'
required: false
example: '20'
schema:
type: string
- name: recent
in: query
description: short cut for last visit timestamp desc [t,true,]
required: false
example: 'true'
schema:
type: boolean
- name: segments
in: query
description: JSON of ad-hoc segment, or pass this in http Body
required: false
example: '{rules...}'
schema:
type: string
- name: fields
in: query
description: list of fields to include in response
required: false
example: email,user_id,name
schema:
type: string
x-operation-id-source: normalized
x-operation-id-original: Segment Batch Delete
/api/segment/{segId}/attribution:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentAttributionListModel'
examples:
response:
value:
data:
- id: '1234'
metrics:
- ts: '1413149713466'
value: 1002
- ts: '1413149713455'
value: 1005
- id: '1111'
metrics:
- ts: '1413149713466'
value: 1002
- ts: '1413149713455'
value: 1005
security:
- ApiKeyAuth: []
summary: SegmentAttribution
operationId: SegmentAttribution
description: Get single attribution
tags:
- Segment
parameters:
- name: account_id
in: query
description: Your Lytics account ID.
required: false
schema:
type: string
- name: segId
in: path
description: segment id
required: true
example: 123abc
schema:
type: string
- name: limit
in: query
description: ''
required: false
schema:
type: integer
default: 168
- name: refresh
in: query
description: ''
required: false
schema:
type: boolean
default: 'true'
/api/segment/attribution:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentAttributionListModel'
examples:
response:
value:
data:
- id: '1234'
metrics:
- ts: '1413149713466'
value: 1002
- ts: '1413149713455'
value: 1005
- id: '1111'
metrics:
- ts: '1413149713466'
value: 1002
- ts: '1413149713455'
value: 1005
security:
- ApiKeyAuth: []
summary: SegmentAttributionList
operationId: SegmentAttributionList
description: Get bunch of segment sizes
tags:
- Segment
parameters:
- name: account_id
in: query
description: Your Lytics account ID.
required: false
schema:
type: string
- name: refresh
in: query
description: 'SYSADMIN ONLY, refresh cache
+ Default `false`'
required: false
schema:
type: boolean
- name: limit
in: query
description: 'number of historical data points to fetch
+ Default `168`'
required: false
schema:
type: integer
- name: ids
in: query
description: list of ids to get, format = ids[]=123&ids[]=234 OR ids=123,345 etc, see standard []string param doc
required: true
example: 123,456
schema:
type: string
/api/segment/{segId}/fieldinfo:
get:
responses:
'200':
description: OK
headers: {}
content:
'*/*':
schema:
$ref: '#/components/schemas/SegmentFieldInfoModel'
security:
- ApiKeyAuth: []
summary: SegmentFieldInfo
operationId: SegmentFieldInfo
description: Get field info by segment
tags:
- Segment
parameters:
- name: account_id
in: query
description: Your Lytics account ID.
required: false
schema:
type: string
- name: segId
in: path
description: the segment id
required: true
example: 123,abc,def
schema:
type: string
- name: limit
in: query
description: ''
required: false
schema:
type: integer
default: 20
- name: fields
in: query
description: optional list, or comma separated list of string fields to include
required: false
example: name,email,segments
schema:
type: string
components:
schemas:
SegmentFieldInfoModel: {}
SegmentScanModel: {}
SegmentAttributionListModel:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
metrics:
type: array
items:
type: object
properties:
ts:
type: string
value:
type: number
required:
- ts
- value
required:
- id
- metrics
example:
data:
- id: '1234'
metrics:
- ts: '1413149713466'
value: 1002
- ts: '1413149713455'
value: 1005
- id: '1111'
metrics:
- ts: '1413149713466'
value: 1002
- ts: '1413149713455'
value: 1005
SegmentSizesModel:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
slug_name:
type: string
size:
type: number
type:
type: string
required:
- id
- slug_name
- size
example:
data:
- id: 456dert
name: Active
slug_name: active
size: 10402
- id: 1234abcd
type: custom
slug_name: active
size: 45236
SegmentSizeModel:
type: object
properties:
data:
type: object
properties:
id:
type: string
name:
type: string
slug_name:
type: string
size:
type: number
example:
data:
id: ''
name: active
slug_name: active
size: 10402
SegmentValidateModel:
type: object
properties:
status:
type: number
message:
type: string
data: {}
example:
status: 200
message: success
data: null
SegmentModel:
type: object
properties:
data:
type: object
properties:
id:
type: string
account_id:
type: string
author_id:
type: string
kind:
type: string
segment_ql:
type: string
created:
type: string
updated:
type: string
description:
type: string
name:
type: string
slug_name:
type: string
tags:
type: array
items:
type: string
example:
data:
id: 7a7f76ff97ad0e3e96c162f74aee8f8f
account_id: 4f7b525bdba058fc096757a6
author_id: 4f7b525bdba058fc096757a6
kind: segment
segment_ql: FILTER AND ( visits > 5, last_visit >= "2015-04-01 00:00:00Z", last_visit < "2015-04-02 00:00:00Z")
created: '2014-08-04T21:18:20.124Z'
updated: '2014-08-04T21:18:20.124Z'
description: Casual users have been active in the last 90 days and show no extreme behavioral patterns.
name: Recent Visits
slug_name: recent_visits
tags:
- email_trigger
SegmentListModel:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
account_id:
type: string
author_id:
type: string
kind:
type: string
segment_ql:
type: string
created:
type: string
updated:
type: string
description:
type: string
is_public:
type: boolean
name:
type: string
slug_name:
type: string
tags:
type: array
items:
type: string
example:
data:
- id: 7a7f76ff97ad0e3e96c162f74aee8f8f
account_id: 4f7b525bdba058fc096757a6
author_id: user_12345
kind: segment
segment_ql: FILTER AND ( visits > 5, last_visit >= "2015-04-01 00:00:00Z", last_visit < "2015-04-02 00:00:00Z")
created: '2014-08-04T21:18:20.124Z'
updated: '2014-08-04T21:18:20.124Z'
description: Casual users have been active in the last 90 days and show no extreme behavioral patterns.
is_public: true
name: Recent Visits
slug_name: recent_visits
tags:
- email_trigger
securitySchemes:
ApiKeyAuth:
in: header
name: Authorization
type: apiKey
x-readme:
explorer-enabled: true
proxy-enabled: true