DEV3 Nudgeflare REST API
Base URL /api/v1 · Authenticate with Authorization: Bearer nf_sk_… · OpenAPI 3.1 JSON
/api/v1/sitesscope: campaigns:readList sites (VAPID public key included, private key never)
/api/v1/sites/{id}scope: campaigns:readGet a site
Parameters: id (path)
/api/v1/subscribersscope: subscribers:readList subscribers (masked endpoint hash, never the endpoint or keys)
Parameters: siteId (query), status (query), tag (query), country (query), externalId (query), limit (query), cursor (query)
/api/v1/subscribers/{id}scope: subscribers:readGet a subscriber
Parameters: id (path)
/api/v1/subscribers/{id}scope: subscribers:writeUpdate tags, attributes or the external id
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"addTags": {
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9 _:.\\-/]{0,63}$"
}
},
"removeTags": {
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9 _:.\\-/]{0,63}$"
}
},
"attributes": {
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,31}$"
},
"additionalProperties": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "number"
},
{
"type": "boolean"
}
]
}
},
"externalId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 128
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}/api/v1/subscribers/{id}scope: subscribers:writeDelete a subscriber
Parameters: id (path)
/api/v1/segmentsscope: subscribers:readList segments
/api/v1/segmentsscope: subscribers:writeCreate a segment (allow-listed rule builder)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"siteIds": {
"default": [],
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
}
},
"rules": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"required": [
"name",
"siteIds",
"rules"
],
"additionalProperties": false
}/api/v1/segments/estimatescope: subscribers:readEstimate the audience of a saved segment or of ad-hoc rules
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"segmentId": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
},
"siteIds": {
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
}
},
"rules": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"additionalProperties": false
}/api/v1/segments/{id}scope: subscribers:readGet a segment
Parameters: id (path)
/api/v1/segments/{id}scope: subscribers:writeUpdate a segment
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"siteIds": {
"default": [],
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
}
},
"rules": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"additionalProperties": false
}/api/v1/segments/{id}scope: subscribers:writeDelete a segment
Parameters: id (path)
/api/v1/campaignsscope: campaigns:readList campaigns
Parameters: status (query), limit (query)
/api/v1/campaignsscope: campaigns:writeCreate a draft campaign (title ≤ 65, body ≤ 240, ≤ 2 buttons, optional A/B)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"siteIds": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
}
},
"segmentIds": {
"default": [],
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
}
},
"variants": {
"minItems": 1,
"maxItems": 4,
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"pattern": "^[A-D]$"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 65
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"icon": {
"anyOf": [
{
"type": "string",
"maxLength": 2048
},
{
"type": "null"
}
]
},
"image": {
"anyOf": [
{
"type": "string",
"maxLength": 2048
},
{
"type": "null"
}
]
},
"buttons": {
"default": [],
"maxItems": 2,
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 24
},
"url": {
"type": "string",
"maxLength": 2048
}
},
"required": [
"label",
"url"
],
"additionalProperties": false
}
},
"url": {
"type": "string",
"maxLength": 2048
},
"utm": {
"anyOf": [
{
"type": "object",
"properties": {
"source": {
"type": "string",
"maxLength": 120
},
"medium": {
"type": "string",
"maxLength": 120
},
"campaign": {
"type": "string",
"maxLength": 120
},
"term": {
"type": "string",
"maxLength": 120
},
"content": {
"type": "string",
"maxLength": 120
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"key",
"title",
"body",
"buttons",
"url"
],
"additionalProperties": false
}
},
"ab": {
"default": {
"enabled": false,
"testPct": 20,
"metric": "ctr",
"decideAfterHours": 4,
"minClicks": 100,
"fallback": "A"
},
"type": "object",
"properties": {
"enabled": {
"default": false,
"type": "boolean"
},
"testPct": {
"default": 20,
"type": "integer",
"minimum": 5,
"maximum": 50
},
"metric": {
"default": "ctr",
"type": "string",
"const": "ctr"
},
"decideAfterHours": {
"default": 4,
"type": "integer",
"minimum": 1,
"maximum": 168
},
"minClicks": {
"default": 100,
"type": "integer",
"minimum": 1,
"maximum": 100000
},
"fallback": {
"default": "A",
"type": "string",
"enum": [
"A",
"both"
]
}
},
"required": [
"enabled",
"testPct",
"metric",
"decideAfterHours",
"minClicks",
"fallback"
],
"additionalProperties": false
},
"schedule": {
"default": {
"mode": "now",
"throttlePerMin": 0
},
"type": "object",
"properties": {
"mode": {
"default": "now",
"type": "string",
"enum": [
"now",
"at",
"local"
]
},
"at": {},
"localDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"localTime": {
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
},
"throttlePerMin": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 1000000
}
},
"required": [
"mode",
"throttlePerMin"
],
"additionalProperties": false
},
"ttl": {
"default": 86400,
"type": "integer",
"minimum": 0,
"maximum": 2419200
},
"urgency": {
"default": "normal",
"type": "string",
"enum": [
"very-low",
"low",
"normal",
"high"
]
}
},
"required": [
"name",
"siteIds",
"segmentIds",
"variants",
"ab",
"schedule",
"ttl",
"urgency"
],
"additionalProperties": false
}/api/v1/campaigns/{id}scope: campaigns:readGet a campaign
Parameters: id (path)
/api/v1/campaigns/{id}scope: campaigns:writeReplace a draft campaign
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"siteIds": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
}
},
"segmentIds": {
"default": [],
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
}
},
"variants": {
"minItems": 1,
"maxItems": 4,
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"pattern": "^[A-D]$"
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 65
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"icon": {
"anyOf": [
{
"type": "string",
"maxLength": 2048
},
{
"type": "null"
}
]
},
"image": {
"anyOf": [
{
"type": "string",
"maxLength": 2048
},
{
"type": "null"
}
]
},
"buttons": {
"default": [],
"maxItems": 2,
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 24
},
"url": {
"type": "string",
"maxLength": 2048
}
},
"required": [
"label",
"url"
],
"additionalProperties": false
}
},
"url": {
"type": "string",
"maxLength": 2048
},
"utm": {
"anyOf": [
{
"type": "object",
"properties": {
"source": {
"type": "string",
"maxLength": 120
},
"medium": {
"type": "string",
"maxLength": 120
},
"campaign": {
"type": "string",
"maxLength": 120
},
"term": {
"type": "string",
"maxLength": 120
},
"content": {
"type": "string",
"maxLength": 120
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"key",
"title",
"body",
"buttons",
"url"
],
"additionalProperties": false
}
},
"ab": {
"default": {
"enabled": false,
"testPct": 20,
"metric": "ctr",
"decideAfterHours": 4,
"minClicks": 100,
"fallback": "A"
},
"type": "object",
"properties": {
"enabled": {
"default": false,
"type": "boolean"
},
"testPct": {
"default": 20,
"type": "integer",
"minimum": 5,
"maximum": 50
},
"metric": {
"default": "ctr",
"type": "string",
"const": "ctr"
},
"decideAfterHours": {
"default": 4,
"type": "integer",
"minimum": 1,
"maximum": 168
},
"minClicks": {
"default": 100,
"type": "integer",
"minimum": 1,
"maximum": 100000
},
"fallback": {
"default": "A",
"type": "string",
"enum": [
"A",
"both"
]
}
},
"required": [
"enabled",
"testPct",
"metric",
"decideAfterHours",
"minClicks",
"fallback"
],
"additionalProperties": false
},
"schedule": {
"default": {
"mode": "now",
"throttlePerMin": 0
},
"type": "object",
"properties": {
"mode": {
"default": "now",
"type": "string",
"enum": [
"now",
"at",
"local"
]
},
"at": {},
"localDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"localTime": {
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
},
"throttlePerMin": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 1000000
}
},
"required": [
"mode",
"throttlePerMin"
],
"additionalProperties": false
},
"ttl": {
"default": 86400,
"type": "integer",
"minimum": 0,
"maximum": 2419200
},
"urgency": {
"default": "normal",
"type": "string",
"enum": [
"very-low",
"low",
"normal",
"high"
]
}
},
"required": [
"name",
"siteIds",
"segmentIds",
"variants",
"ab",
"schedule",
"ttl",
"urgency"
],
"additionalProperties": false
}/api/v1/campaigns/{id}scope: campaigns:writeDelete a draft or cancelled campaign
Parameters: id (path)
/api/v1/campaigns/{id}/sendscope: campaigns:sendSend now (exactly one delivery per subscriber, even if called twice)
Parameters: id (path)
/api/v1/campaigns/{id}/schedulescope: campaigns:sendSchedule at a UTC time or at a local time per timezone
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"at",
"local"
]
},
"at": {
"type": "string"
},
"localDate": {
"type": "string"
},
"localTime": {
"type": "string"
},
"throttlePerMin": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"mode"
],
"additionalProperties": false
}/api/v1/campaigns/{id}/cancelscope: campaigns:sendCancel a campaign
Parameters: id (path)
/api/v1/campaigns/{id}/statsscope: campaigns:readResults per variant and per timezone wave
Parameters: id (path)
/api/v1/automations/{key}/triggerscope: automations:triggerTrigger an API automation for subscribers (idempotent per key)
Parameters: key (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"externalIds": {
"maxItems": 1000,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"subscriberIds": {
"maxItems": 1000,
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
}
},
"segmentId": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
},
"idempotencyKey": {
"type": "string",
"minLength": 8,
"maxLength": 128
},
"override": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 65
},
"body": {
"type": "string",
"maxLength": 240
},
"url": {
"type": "string",
"maxLength": 2048
}
},
"additionalProperties": false
}
},
"required": [
"idempotencyKey"
],
"additionalProperties": false
}/api/v1/notificationsscope: automations:triggerOne-off transactional push to an external id
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"externalId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"siteId": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
},
"idempotencyKey": {
"type": "string",
"minLength": 8,
"maxLength": 128
},
"content": {
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 65
},
"body": {
"type": "string",
"maxLength": 240
},
"url": {
"type": "string",
"maxLength": 2048
},
"icon": {
"type": [
"string",
"null"
]
},
"image": {
"type": [
"string",
"null"
]
},
"buttons": {
"maxItems": 2,
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"maxLength": 24
},
"url": {
"type": "string",
"maxLength": 2048
}
},
"required": [
"label",
"url"
],
"additionalProperties": false
}
}
},
"required": [
"title",
"body",
"url"
],
"additionalProperties": false
},
"ttl": {
"type": "integer",
"minimum": 0,
"maximum": 2419200
},
"urgency": {
"type": "string",
"enum": [
"very-low",
"low",
"normal",
"high"
]
}
},
"required": [
"externalId",
"idempotencyKey",
"content"
],
"additionalProperties": false
}/api/v1/analyticsscope: analytics:readDaily delivery and click analytics
Parameters: siteId (query), campaignId (query), from (query), to (query)