API reference
In-app
In-app templates and settings, and the two calls the app SDK makes.
In-app templates and settings, and the two calls the app SDK makes.
POST /v1/broadcasts/{id}/end#
End a live in-app campaign now
The campaign becomes sent and the app is given its messages no more. In-app campaigns only; 409 when it is not live.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string (uuid) required |
curl -X POST "$SAPAGAN_URL/v1/broadcasts/user-42/end" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/broadcasts/user-42/end`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"id": "user-42",
"status": "<status>"
}GET /v1/inapp-templates#
The in-app starters this workspace is offered and the organisation's in-app templates
Marketplace starters (they open a product) are listed only in a marketplace workspace; so are the organisation's templates that open a store, catalog, product or voucher.
curl -X GET "$SAPAGAN_URL/v1/inapp-templates" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/inapp-templates`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"marketplace": true,
"starters": [
{
"key": "<key>",
"audience": "general",
"ids": {
"en": "<en>",
"id": "user-42"
},
"name": {
"en": "<en>",
"id": "user-42"
},
"description": {
"en": "<en>",
"id": "user-42"
},
"content": {
"en": {},
"id": {}
}
}
],
"organisation": [
{
"id": "user-42",
"name": "order_placed",
"description": "<description>",
"workspaceId": "<workspaceId>",
"marketplaceOnly": true,
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"content": {}
}
]
}POST /v1/inapp-templates#
Save an in-app campaign or in-app content as a template of the organisation (operator)
Give broadcastId (one of this workspace's in-app campaigns) or content (in-app content). Its end (rules.endsAt, rules.expiresAfterHours) is left out. The in-app rules check it for this workspace (400 invalid_content); names are unique per organisation (409 name_taken). Every workspace of the organisation sees it (one that opens a product, marketplaces only). Audited.
Request body
| Field | Type | Notes |
|---|---|---|
name required | string | min 1, max 120 |
description | string | max 500 |
broadcastId | string | max 100 |
content | object |
curl -X POST "$SAPAGAN_URL/v1/inapp-templates" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "order_placed"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/inapp-templates`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "order_placed"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"name": "order_placed",
"description": "<description>",
"workspaceId": "<workspaceId>",
"marketplaceOnly": true,
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"content": {}
}GET /v1/inapp-templates/{id}#
One in-app template to use here, with what the in-app rules refuse in this workspace
id is a starter (starter:<key>:<en|id>) or one of the organisation's templates. issues is empty when the content can be used here as it is.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/inapp-templates/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/inapp-templates/user-42`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"id": "user-42",
"source": "starter",
"name": "order_placed",
"description": "<description>",
"locale": "en",
"content": {},
"issues": [
{
"field": "<field>",
"message": "<message>"
}
]
}PATCH /v1/inapp-templates/{id}#
Rename an in-app template, or change its description (operator)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
name | string | min 1, max 120 |
description | string | max 500 |
curl -X PATCH "$SAPAGAN_URL/v1/inapp-templates/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "order_placed",
"description": "<description>"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/inapp-templates/user-42`, {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "order_placed",
"description": "<description>"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"name": "order_placed",
"description": "<description>",
"workspaceId": "<workspaceId>",
"marketplaceOnly": true,
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"content": {}
}DELETE /v1/inapp-templates/{id}#
Remove an in-app template (operator)
Messages already made from it are not affected. Audited, with the content it had.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X DELETE "$SAPAGAN_URL/v1/inapp-templates/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/inapp-templates/user-42`, {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"id": "user-42",
"removed": true
}POST /v1/inapp/events#
Report an in-app message shown, clicked or dismissed (app SDK)
Recorded once per delivery and event; a click or dismissal records the show too when it was not reported. Always 202: recorded is false for a repeat and, identically, for an unknown or foreign delivery or a profileId that is not the recipient.
Request body
| Field | Type | Notes |
|---|---|---|
deliveryId required | string | |
event required | "shown" | "clicked" | "dismissed" | |
at required | string (date-time) | |
profileId required | string | min 1, max 200 |
buttonIndex | integer or null | min 0, max 1 |
platform | "android" | "ios" | "web" |
curl -X POST "$SAPAGAN_URL/v1/inapp/events" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"deliveryId": "<deliveryId>",
"event": "shown",
"at": "2026-11-17T09:30:00+07:00",
"profileId": "user-42"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/inapp/events`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"deliveryId": "<deliveryId>",
"event": "shown",
"at": "2026-11-17T09:30:00+07:00",
"profileId": "user-42"
}),
});
const data = await res.json();Responses
{
"recorded": true
}GET /v1/inapp/messages#
The in-app messages the app may show this person now (app SDK)
The app's ingest key plus the person's token in X-Sapagan-User-Token: an identity token signed by your backend or your registered session JWT (required in production workspaces; its subject must be userId). Messages come rendered for the person with the rules the SDK applies on the device; denyScreens lists screens (exact, ignoring case, or a prefix ending in *) on which nothing is ever shown. ETag and If-None-Match give 304 when nothing changed.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
userId | query | string required | |
appId | query | string | |
platform | query | "android" | "ios" | "web" |
curl -X GET "$SAPAGAN_URL/v1/inapp/messages?userId=%3CuserId%3E" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/inapp/messages?userId=%3CuserId%3E`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"messages": [
{
"id": "user-42",
"messageId": "<messageId>",
"format": "banner_top",
"slot": "<slot>",
"title": "Pesanan dikirim",
"body": "Pesanan #1042 sedang dalam perjalanan.",
"imageUrl": "<imageUrl>",
"link": "<link>",
"buttons": [
{
"label": "Order service",
"style": "primary",
"action": "link",
"link": "<link>"
}
],
"dismissible": true,
"trigger": {
"kind": "app_open"
},
"priority": 1,
"perSessionCap": 1,
"perDayCap": 1,
"expiresAt": "<expiresAt>"
}
],
"denyScreens": [
"<denyScreens>"
],
"refreshAfterSeconds": 1
}GET /v1/workspace/inapp-settings#
The workspace's in-app settings (screens never shown on)
curl -X GET "$SAPAGAN_URL/v1/workspace/inapp-settings" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/workspace/inapp-settings`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"denyScreens": [
"<denyScreens>"
],
"apps": {}
}PUT /v1/workspace/inapp-settings#
Change the in-app settings (owner); audited with the reason
denyScreens: screens of every app on which no in-app message is shown (a name as the app sends it, ignoring case, or a prefix ending in *); checkout* and payment* are always kept. apps: more screens per app id ({"<appId>": {"denyScreens": [...]}}).
Request body
| Field | Type | Notes |
|---|---|---|
denyScreens | string[] | up to 100 items |
apps | object | |
reason required | string | min 1, max 500 |
curl -X PUT "$SAPAGAN_URL/v1/workspace/inapp-settings" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/workspace/inapp-settings`, {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"denyScreens": [
"<denyScreens>"
],
"apps": {},
"changed": true
}