API reference
Stores
Marketplace workspaces only. Stores, their policies, health, audiences, flows and reports. Own-brand workspaces answer 404.
Marketplace workspaces only. Stores, their policies, health, audiences, flows and reports. Own-brand workspaces answer 404.
GET /v1/flow-reviews#
Store flow content waiting for review, oldest first (workspace keys and console sessions)
The newest version of each flow, in review; aiReview is null while the AI has not answered, otherwise a person decides.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
limit | query | integer |
curl -X GET "$SAPAGAN_URL/v1/flow-reviews" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/flow-reviews`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"items": [
{
"versionId": "<versionId>",
"key": "post_purchase",
"version": 1,
"status": "in_review",
"content": {
"title": "Pesanan dikirim",
"body": "Pesanan #1042 sedang dalam perjalanan.",
"destination": {}
},
"delayMinutes": 1,
"submittedAt": "<submittedAt>",
"submittedBy": "<submittedBy>",
"store": {
"id": "user-42",
"name": "order_placed",
"trustTier": "red"
},
"aiReview": {
"verdict": "<verdict>",
"flags": [
"<flags>"
],
"reason": "Checked with the owner",
"confidence": 1,
"createdAt": "<createdAt>"
}
}
]
}GET /v1/flow-reviews/{id}#
One version of a store's flow content, with the AI's review
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/flow-reviews/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/flow-reviews/user-42`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"versionId": "<versionId>",
"key": "post_purchase",
"version": 1,
"status": "in_review",
"content": {
"title": "Pesanan dikirim",
"body": "Pesanan #1042 sedang dalam perjalanan.",
"imageUrl": "<imageUrl>",
"destination": {}
},
"delayMinutes": 1,
"submittedAt": "<submittedAt>",
"submittedBy": "<submittedBy>",
"store": {
"id": "user-42",
"name": "order_placed",
"trustTier": "red"
},
"aiReview": {
"verdict": "<verdict>",
"flags": [
"<flags>"
],
"reason": "Checked with the owner",
"confidence": 1,
"createdAt": "<createdAt>"
}
}GET /v1/flow-reviews/{id}/image#
The flow content's image as Sapagan fetches it, with its SHA-256 (for the reviewer)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/flow-reviews/user-42/image" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/flow-reviews/user-42/image`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"url": "https://example.com",
"contentType": "<contentType>",
"sha256": "<sha256>",
"size": 1,
"dataBase64": "<dataBase64>"
}GET /v1/scope-appeals#
Open appeals against store blocks, oldest first (workspace keys only; the review queue's appeal entries)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
limit | query | integer |
curl -X GET "$SAPAGAN_URL/v1/scope-appeals" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope-appeals`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"appeals": [
{
"id": "user-42",
"scopeId": "<scopeId>",
"blockId": "<blockId>",
"message": "<message>",
"status": "open",
"submittedBy": "<submittedBy>",
"submittedAt": "<submittedAt>",
"decidedAt": "<decidedAt>",
"decidedBy": "<decidedBy>",
"decisionNote": "<decisionNote>",
"block": {
"id": "user-42",
"scopeId": "<scopeId>",
"category": "spam",
"reason": "Checked with the owner",
"startsAt": "<startsAt>",
"endsAt": "<endsAt>",
"permanent": true,
"createdBy": "<createdBy>",
"endedAt": "<endedAt>",
"endReason": "<endReason>",
"endedBy": "<endedBy>",
"endNote": "<endNote>"
}
}
]
}POST /v1/scope-appeals/{id}/decision#
Grant (lifts the block) or deny an appeal (workspace keys only); the note is shown to the seller; audited
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
decision required | "grant" | "deny" | |
note required | string | min 1, max 2000 |
curl -X POST "$SAPAGAN_URL/v1/scope-appeals/user-42/decision" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"decision": "grant",
"note": "Looks good"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope-appeals/user-42/decision`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"decision": "grant",
"note": "Looks good"
}),
});
const data = await res.json();Responses
{
"appeal": {
"id": "user-42",
"scopeId": "<scopeId>",
"blockId": "<blockId>",
"message": "<message>",
"status": "open",
"submittedBy": "<submittedBy>",
"submittedAt": "<submittedAt>",
"decidedAt": "<decidedAt>",
"decidedBy": "<decidedBy>",
"decisionNote": "<decisionNote>"
},
"block": {
"id": "user-42",
"scopeId": "<scopeId>",
"category": "spam",
"reason": "Checked with the owner",
"startsAt": "<startsAt>",
"endsAt": "<endsAt>",
"permanent": true,
"createdBy": "<createdBy>",
"endedAt": "<endedAt>",
"endReason": "<endReason>",
"endedBy": "<endedBy>",
"endNote": "<endNote>"
}
}GET /v1/scope-health-appeals#
Open appeals against automatic pauses, oldest first (workspace keys only; the review queue's entries)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
limit | query | integer |
curl -X GET "$SAPAGAN_URL/v1/scope-health-appeals" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope-health-appeals`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"appeals": [
{
"id": "user-42",
"scopeId": "<scopeId>",
"pauseId": "<pauseId>",
"message": "<message>",
"status": "open",
"submittedBy": "<submittedBy>",
"submittedAt": "<submittedAt>",
"decidedAt": "<decidedAt>",
"decidedBy": "<decidedBy>",
"decisionNote": "<decisionNote>",
"pause": {
"id": "user-42",
"scopeId": "<scopeId>",
"reasons": [
"complaint_rate"
],
"signals": {},
"stepBefore": 1,
"stepAfter": 1,
"trustBefore": "<trustBefore>",
"trustAfter": "<trustAfter>",
"pausedAt": "<pausedAt>",
"alertedAt": "<alertedAt>",
"endedAt": "<endedAt>",
"endReason": "resumed",
"endedBy": "<endedBy>",
"endNote": "<endNote>"
}
}
]
}POST /v1/scope-health-appeals/{id}/decision#
Grant (ends the automatic pause and resumes the store) or deny an appeal against an automatic pause; operator sessions only (reviewer role; a workspace key is 403 operator_required); the note is shown to the seller; audited
A store an operator paused again by hand since the automatic pause stays paused when the appeal is granted: only the automatic pause ends.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
decision required | "grant" | "deny" | |
note required | string | min 3, max 2000 |
curl -X POST "$SAPAGAN_URL/v1/scope-health-appeals/user-42/decision" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"decision": "grant",
"note": "Looks good"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope-health-appeals/user-42/decision`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"decision": "grant",
"note": "Looks good"
}),
});
const data = await res.json();Responses
{
"appeal": {
"id": "user-42",
"scopeId": "<scopeId>",
"pauseId": "<pauseId>",
"message": "<message>",
"status": "open",
"submittedBy": "<submittedBy>",
"submittedAt": "<submittedAt>",
"decidedAt": "<decidedAt>",
"decidedBy": "<decidedBy>",
"decisionNote": "<decisionNote>"
},
"pause": {
"id": "user-42",
"scopeId": "<scopeId>",
"reasons": [
"complaint_rate"
],
"signals": {},
"stepBefore": 1,
"stepAfter": 1,
"trustBefore": "<trustBefore>",
"trustAfter": "<trustAfter>",
"pausedAt": "<pausedAt>",
"alertedAt": "<alertedAt>",
"endedAt": "<endedAt>",
"endReason": "resumed",
"endedBy": "<endedBy>",
"endNote": "<endNote>"
}
}GET /v1/scope/audience#
The store's own audiences: total, reachable, reach cap and exclusions (scope keys and tokens)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
kind | query | "buyers" | "followers" | "buyers_and_followers" | "followers_not_buyers" | "buyers_repeat" | "buyers_one_time" | "buyers_lapsed" | "birthday" | "product_viewers" | "abandoned_cart" | "seller_segment" | |
days | query | integer | |
window | query | "today" | "next_7_days" | "this_month" | |
productId | query | string | |
segmentId | query | string | |
channel | query | "push" | "email" |
curl -X GET "$SAPAGAN_URL/v1/scope/audience" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/audience`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"channel": "push",
"asOf": "<asOf>",
"audiences": [
{
"available": true,
"spec": {
"kind": "buyers"
},
"key": "<key>",
"label": "Order service",
"channel": "push",
"reason": "source_unavailable",
"total": 1,
"reachable": 1,
"cap": 1,
"willSend": 1,
"overCap": 1,
"excluded": {
"optedOut": 1,
"unreachable": 1
}
}
],
"unavailableKinds": [
{
"kind": "<kind>",
"label": "Order service",
"reason": "source_unavailable"
}
]
}GET /v1/scope/block#
Whether the store is blocked, why, until when, and its appeal (reachable while blocked)
curl -X GET "$SAPAGAN_URL/v1/scope/block" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/block`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"blocked": true,
"block": {
"category": "spam",
"reason": "Checked with the owner",
"startsAt": "<startsAt>",
"endsAt": "<endsAt>",
"permanent": true,
"appeal": {
"id": "user-42",
"status": "open",
"submittedAt": "<submittedAt>",
"decidedAt": "<decidedAt>",
"decisionNote": "<decisionNote>"
},
"appealsLeft": 1,
"canAppeal": true
}
}POST /v1/scope/block/appeals#
Ask for a review of the store's block (reachable while blocked); lands in the review queue
Request body
| Field | Type | Notes |
|---|---|---|
message required | string | min 1, max 2000 |
curl -X POST "$SAPAGAN_URL/v1/scope/block/appeals" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "<message>"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/block/appeals`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"message": "<message>"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"status": "open",
"submittedAt": "<submittedAt>"
}GET /v1/scope/email-sender#
The store's own email From address and display name (scope keys and tokens)
curl -X GET "$SAPAGAN_URL/v1/scope/email-sender" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/email-sender`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"localPart": "<localPart>",
"address": "<address>",
"displayName": "<displayName>",
"domain": "<domain>"
}GET /v1/scope/flows#
The store's automatic flows: thank you after a purchase and welcome new followers (scope keys and tokens)
Each flow's switch, state (off, in_review, live, paused, rejected with the reason), the content and delay as last saved, the newest and the approved version, and its figures over 30 days (entered, sent, opened, orders; withheld below 5 pushes sent). 404 in an own-brand workspace.
curl -X GET "$SAPAGAN_URL/v1/scope/flows" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/flows`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"flows": [
{
"key": "post_purchase",
"enabled": true,
"status": "off",
"statusReason": "<statusReason>",
"content": {
"title": "Pesanan dikirim",
"body": "Pesanan #1042 sedang dalam perjalanan.",
"destination": {}
},
"delayMinutes": 1,
"delay": {
"min": 1,
"max": 1,
"default": 1,
"choices": [
1
]
},
"draftVersion": 1,
"latest": {
"version": 1,
"status": "in_review",
"content": {
"title": "Pesanan dikirim",
"body": "Pesanan #1042 sedang dalam perjalanan.",
"destination": {}
},
"delayMinutes": 1,
"submittedAt": "<submittedAt>",
"decidedAt": "<decidedAt>",
"note": "Looks good"
},
"approved": {
"version": 1,
"status": "in_review",
"content": {
"title": "Pesanan dikirim",
"body": "Pesanan #1042 sedang dalam perjalanan.",
"destination": {}
},
"delayMinutes": 1,
"submittedAt": "<submittedAt>",
"decidedAt": "<decidedAt>",
"note": "Looks good"
},
"planAllows": true,
"updatedAt": "<updatedAt>",
"stats": {
"days": 1,
"entered": 1,
"withheld": true,
"sent": 1,
"opened": 1,
"orders": 1,
"revenue": 1
}
}
]
}PUT /v1/scope/flows/{key}#
Switch a flow on or off, or change its push and delay (scope keys and tokens); a change goes to review
content is a store's push (title, body, optional imageUrl on an allowed host, destination: store, catalog, product or voucher). delayMinutes within the flow's bounds. A changed content or delay is a new version for review: until it is approved the flow takes nobody new and sends nothing. Switching on needs a plan with flows (409 plan_required). expectedDraftVersion (the draftVersion read) refuses a lost update with 409 flow_changed.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
key | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
enabled | boolean | |
content | any | |
delayMinutes | integer | |
expectedDraftVersion | integer | min 0 |
curl -X PUT "$SAPAGAN_URL/v1/scope/flows/welcome" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"content": null,
"delayMinutes": 1,
"expectedDraftVersion": 0
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/flows/welcome`, {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"enabled": true,
"content": null,
"delayMinutes": 1,
"expectedDraftVersion": 0
}),
});
const data = await res.json();Responses
{
"flow": {
"key": "post_purchase",
"enabled": true,
"status": "off",
"statusReason": "<statusReason>",
"content": {
"title": "Pesanan dikirim",
"body": "Pesanan #1042 sedang dalam perjalanan.",
"imageUrl": "<imageUrl>",
"destination": {}
},
"delayMinutes": 1,
"delay": {
"min": 1,
"max": 1,
"default": 1,
"choices": [
1
]
},
"draftVersion": 1,
"latest": {
"version": 1,
"status": "in_review",
"content": {
"title": "Pesanan dikirim",
"body": "Pesanan #1042 sedang dalam perjalanan.",
"destination": {}
},
"delayMinutes": 1,
"submittedAt": "<submittedAt>",
"decidedAt": "<decidedAt>",
"note": "Looks good"
},
"approved": {
"version": 1,
"status": "in_review",
"content": {
"title": "Pesanan dikirim",
"body": "Pesanan #1042 sedang dalam perjalanan.",
"destination": {}
},
"delayMinutes": 1,
"submittedAt": "<submittedAt>",
"decidedAt": "<decidedAt>",
"note": "Looks good"
},
"planAllows": true,
"updatedAt": "<updatedAt>",
"stats": {
"days": 1,
"entered": 1,
"withheld": true,
"sent": 1,
"opened": 1,
"orders": 1,
"revenue": 1
}
}
}GET /v1/scope/health#
Whether the store is paused for its health, why, its appeal, and its ramp progress (scope keys and tokens)
Aggregates of the store's own sends only: rates rounded to 0.1 percentage point, every number withheld (withheld) below 5 sends. Never a buyer.
curl -X GET "$SAPAGAN_URL/v1/scope/health" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/health`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"autoPaused": true,
"pause": {
"reasons": [
"complaint_rate"
],
"pausedAt": "<pausedAt>",
"windowDays": 1,
"withheld": true,
"signals": [
{
"signal": "complaint_rate",
"value": 1,
"threshold": 1
}
],
"stepBefore": 1,
"stepAfter": 1,
"appeal": {
"id": "user-42",
"status": "open",
"submittedAt": "<submittedAt>",
"decidedAt": "<decidedAt>",
"decisionNote": "<decisionNote>"
},
"appealsLeft": 1,
"canAppeal": true
},
"ramp": {
"step": 1,
"campaigns": 1,
"campaignsNeeded": 1,
"held": true
}
}POST /v1/scope/health/appeals#
Ask for a review of the store's automatic pause; lands in the review queue
Request body
| Field | Type | Notes |
|---|---|---|
message required | string | min 1, max 2000 |
curl -X POST "$SAPAGAN_URL/v1/scope/health/appeals" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "<message>"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/health/appeals`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"message": "<message>"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"status": "open",
"submittedAt": "<submittedAt>"
}GET /v1/scope/policy#
The store's own policy: tier, reach cap, quotas, trust tier, ramp step, pause state (scope keys and tokens)
quietHours is the window in which marketing is not sent (wall clock in timeZone, the workspace's): a broadcast scheduled inside it moves to its end (P1-06).
curl -X GET "$SAPAGAN_URL/v1/scope/policy" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/policy`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"scopeId": "<scopeId>",
"stored": true,
"planCode": "<planCode>",
"tier": "free",
"trustTier": "red",
"rampStep": 1,
"reachCap": 1,
"effectiveReachCap": 1,
"fullReachCap": 1,
"quotas": {},
"monthlyQuota": {
"push": 1,
"email": 1,
"inapp": 1
},
"dailyMax": 1,
"effectiveDailyMax": 1,
"campaignsPerWeek": 1,
"allowedChannels": [
"push"
],
"frequencyCap": {},
"segmentCooldownHours": 1,
"contactAccess": "masked",
"status": "<status>",
"paused": true,
"pausedReason": "<pausedReason>",
"pausedAt": "<pausedAt>",
"updatedAt": "<updatedAt>",
"quietHours": {
"start": "<start>",
"end": "<end>",
"timeZone": "<timeZone>"
}
}GET /v1/scope/products#
Search the store's own products (scope keys and tokens)
The credential's own store only: there is no store parameter, and another store's product id in ids is simply absent. Archived and deleted listings are left out. Products come from the Toco connector's product sync (a few minutes behind Toco).
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
q | query | string | Words of the product's name, anywhere in it, any case. |
ids | query | string | Comma-separated listing ids (at most 50): exactly these, when they are the store's own and live. |
cursor | query | string | |
limit | query | integer |
curl -X GET "$SAPAGAN_URL/v1/scope/products" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/products`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"products": [
{
"id": "user-42",
"name": "order_placed",
"imageUrl": "<imageUrl>",
"price": 1,
"specialPrice": 1,
"stock": 1,
"sold": 1,
"updatedAt": "<updatedAt>"
}
],
"nextCursor": "<nextCursor>"
}GET /v1/scope/reports#
The store's own report: sent, opened, clicked, orders and revenue per campaign and per day, week or month (store credentials)
Campaigns dispatched from from to to (days in the workspace's time zone, both included; default the last 30 days, at most 366), optionally one channel. A campaign counts in the period it was dispatched, with every open, click and order attributed to it. Each campaign is P1-10's store view: fewer than 5 sent, every number null and the campaign left out of the sums; 1 to 4 not sent, sent rounded. flows holds the store's automatic flows per flow and period (the same withheld rule; a flow's numbers count on the day they happened; its orders are never a campaign's). Aggregates only: no person, recipient or reason. A range holding more than 2,000 campaigns is 400 too_many_campaigns (never cut); 429 past 30 reports a minute per store; 503 report_timeout when a statement runs past 5 seconds.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
from | query | string | |
to | query | string | |
granularity | query | "day" | "week" | "month" | |
channel | query | "push" | "email" | "inapp" |
curl -X GET "$SAPAGAN_URL/v1/scope/reports" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/reports`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"timeZone": "<timeZone>",
"from": "<from>",
"to": "<to>",
"granularity": "day",
"channel": "push",
"currency": "<currency>",
"opensTracked": true,
"totals": {
"campaigns": 1,
"withheldCampaigns": 1,
"roundedCampaigns": 1,
"sent": 1,
"opened": 1,
"clicked": 1,
"orders": 1,
"revenue": 1,
"openRate": 1,
"clickRate": 1
},
"periods": [
{
"campaigns": 1,
"withheldCampaigns": 1,
"roundedCampaigns": 1,
"sent": 1,
"opened": 1,
"clicked": 1,
"orders": 1,
"revenue": 1,
"openRate": 1,
"clickRate": 1,
"start": "<start>"
}
],
"campaigns": [
{
"id": "user-42",
"name": "order_placed",
"channel": "push",
"dispatchedAt": "<dispatchedAt>",
"period": "<period>",
"withheld": true,
"rounded": true,
"sent": 1,
"opened": 1,
"clicked": 1,
"orders": 1,
"revenue": 1,
"openRate": 1,
"clickRate": 1
}
],
"flows": {
"totals": {
"rows": 1,
"withheldRows": 1,
"sent": 1,
"opened": 1,
"orders": 1,
"revenue": 1,
"openRate": 1
},
"periods": [
{
"rows": 1,
"withheldRows": 1,
"sent": 1,
"opened": 1,
"orders": 1,
"revenue": 1,
"openRate": 1,
"start": "<start>"
}
],
"rows": [
{
"flow": "post_purchase",
"period": "<period>",
"withheld": true,
"sent": 1,
"opened": 1,
"orders": 1,
"revenue": 1
}
]
}
}GET /v1/scope/usage#
The store's own campaign usage this calendar month (workspace time zone)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
at | query | string (date-time) |
curl -X GET "$SAPAGAN_URL/v1/scope/usage" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/usage`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"scopeId": "<scopeId>",
"period": "<period>",
"timeZone": "<timeZone>",
"dailyMax": 1,
"channels": [
{
"channel": "push",
"used": 1,
"extra": 1,
"credits": 1,
"quota": 1,
"remaining": 1
}
]
}GET /v1/scopes#
The workspace's stores with tier, pause and block state (workspace keys only); blocked first, then paused, then by name
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
q | query | string | |
filter | query | "all" | "blocked" | "paused" | |
limit | query | integer | |
offset | query | integer |
curl -X GET "$SAPAGAN_URL/v1/scopes" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"total": 1,
"scopes": [
{
"id": "user-42",
"type": "<type>",
"externalId": "user-42",
"name": "order_placed",
"status": "<status>",
"shortName": "<shortName>",
"tier": "<tier>",
"trustTier": "<trustTier>",
"pausedReason": "<pausedReason>",
"blocked": true,
"blockEndsAt": "<blockEndsAt>",
"blockCategory": "<blockCategory>"
}
]
}GET /v1/scopes/{id}#
Read a scope
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/scopes/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"id": "user-42",
"type": "<type>",
"externalId": "user-42",
"name": "order_placed",
"status": "<status>",
"shortName": "<shortName>"
}GET /v1/scopes/{id}/audience#
A store's audiences with the full exclusion waterfall (workspace keys only)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
kind | query | "buyers" | "followers" | "buyers_and_followers" | "followers_not_buyers" | "buyers_repeat" | "buyers_one_time" | "buyers_lapsed" | "birthday" | "product_viewers" | "abandoned_cart" | "seller_segment" | |
days | query | integer | |
window | query | "today" | "next_7_days" | "this_month" | |
productId | query | string | |
segmentId | query | string | |
channel | query | "push" | "email" | "inapp" | |
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/scopes/user-42/audience" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/audience`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"channel": "push",
"asOf": "<asOf>",
"audiences": [
{
"available": true,
"spec": {
"kind": "buyers"
},
"key": "<key>",
"label": "Order service",
"channel": "push",
"reason": "source_unavailable",
"detail": "<detail>",
"total": 1,
"reachable": 1,
"cap": 1,
"willSend": 1,
"overCap": 1,
"excluded": {
"unsubscribed": 1,
"no_consent": 1,
"seller_optout": 1,
"suppressed": 1,
"no_address": 1
},
"dropped": {
"profileGone": 1
}
}
],
"unavailableKinds": [
{
"kind": "<kind>",
"label": "Order service",
"reason": "source_unavailable",
"detail": "<detail>"
}
]
}POST /v1/scopes/{id}/block#
Block a store for wrong activity, for some days or permanently (workspace keys only); audited
While blocked: the store's scope keys and tokens get 403 store_blocked except on GET /v1/scope/block and POST /v1/scope/block/appeals; nothing is sent (sendGate scope_blocked); scheduled broadcasts are cancelled and flows paused by the block hooks.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
category required | "spam" | "misleading_offers" | "prohibited_products" | "harassment" | "other" | |
reason required | string | min 3, max 2000 |
days | integer | min 1, max 365 |
permanent | true |
curl -X POST "$SAPAGAN_URL/v1/scopes/user-42/block" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"category": "spam",
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/block`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"category": "spam",
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"scopeId": "<scopeId>",
"category": "spam",
"reason": "Checked with the owner",
"startsAt": "<startsAt>",
"endsAt": "<endsAt>",
"permanent": true,
"createdBy": "<createdBy>",
"endedAt": "<endedAt>",
"endReason": "<endReason>",
"endedBy": "<endedBy>",
"endNote": "<endNote>"
}GET /v1/scopes/{id}/blocks#
A store's blocks, newest first, with their appeals (workspace keys only)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/scopes/user-42/blocks" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/blocks`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"blocks": [
{
"id": "user-42",
"scopeId": "<scopeId>",
"category": "spam",
"reason": "Checked with the owner",
"startsAt": "<startsAt>",
"endsAt": "<endsAt>",
"permanent": true,
"createdBy": "<createdBy>",
"endedAt": "<endedAt>",
"endReason": "<endReason>",
"endedBy": "<endedBy>",
"endNote": "<endNote>",
"appeals": [
{
"id": "user-42",
"scopeId": "<scopeId>",
"blockId": "<blockId>",
"message": "<message>",
"status": "open",
"submittedBy": "<submittedBy>",
"submittedAt": "<submittedAt>",
"decidedAt": "<decidedAt>",
"decidedBy": "<decidedBy>",
"decisionNote": "<decisionNote>"
}
]
}
]
}GET /v1/scopes/{id}/email-sender#
A store's email From address (workspace keys only)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/scopes/user-42/email-sender" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/email-sender`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"localPart": "<localPart>",
"address": "<address>",
"displayName": "<displayName>",
"domain": "<domain>"
}PUT /v1/scopes/{id}/email-sender#
Set or clear a store's From local part (workspace keys only); audited
localPart is 3 to 40 lowercase letters and digits, not a reserved role address (postmaster, abuse, noreply, ...), and unique in the workspace: another store's (or the workspace's own) local part answers 409 local_part_taken. null clears it (the store then sends no email).
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
localPart required | string or null | max 100 |
reason | string | max 500 |
curl -X PUT "$SAPAGAN_URL/v1/scopes/user-42/email-sender" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"localPart": "<localPart>"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/email-sender`, {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"localPart": "<localPart>"
}),
});
const data = await res.json();Responses
{
"localPart": "<localPart>",
"address": "<address>",
"displayName": "<displayName>",
"domain": "<domain>"
}GET /v1/scopes/{id}/health#
A store's health: the latest evaluation, the thresholds, ramp evidence and automatic pauses with their appeals (workspace keys only)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/scopes/user-42/health" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/health`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"scopeId": "<scopeId>",
"health": {
"evaluatedAt": "<evaluatedAt>",
"windowDays": 1,
"status": "healthy",
"counts": {},
"findings": [
{
"signal": "complaint_rate",
"level": "watch",
"value": 1,
"threshold": 1
}
],
"ramp": {}
},
"thresholds": {
"windowDays": 1,
"unsubscribeAttributionHours": 1,
"rejectionWindowDays": 1,
"unsubscribePauseMinRevokers": 1,
"promotionMinCampaignSends": 1,
"thresholds": {
"complaint_rate": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"bounce_rate": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"unsubscribe_rate": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"invalid_token_rate": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"failure_rate": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"review_rejections": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"open_rate_drop": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
}
},
"promotion": {
"1": {
"campaigns": 1,
"minSent": 1,
"maxComplaintRate": 1,
"maxUnsubscribeRate": 1
},
"2": {
"campaigns": 1,
"minSent": 1,
"maxComplaintRate": 1,
"maxUnsubscribeRate": 1
}
},
"pauseDropsStep": true,
"pauseLowersTrust": true,
"pauseOfficial": true
},
"pause": {
"id": "user-42",
"scopeId": "<scopeId>",
"reasons": [
"complaint_rate"
],
"signals": {},
"stepBefore": 1,
"stepAfter": 1,
"trustBefore": "<trustBefore>",
"trustAfter": "<trustAfter>",
"pausedAt": "<pausedAt>",
"alertedAt": "<alertedAt>",
"endedAt": "<endedAt>",
"endReason": "resumed",
"endedBy": "<endedBy>",
"endNote": "<endNote>"
},
"pauses": [
{
"id": "user-42",
"scopeId": "<scopeId>",
"reasons": [
"complaint_rate"
],
"signals": {},
"stepBefore": 1,
"stepAfter": 1,
"trustBefore": "<trustBefore>",
"trustAfter": "<trustAfter>",
"pausedAt": "<pausedAt>",
"alertedAt": "<alertedAt>",
"endedAt": "<endedAt>",
"endReason": "resumed",
"endedBy": "<endedBy>",
"endNote": "<endNote>",
"appeals": [
{
"id": "user-42",
"scopeId": "<scopeId>",
"pauseId": "<pauseId>",
"message": "<message>",
"status": "open",
"submittedBy": "<submittedBy>",
"submittedAt": "<submittedAt>",
"decidedAt": "<decidedAt>",
"decidedBy": "<decidedBy>",
"decisionNote": "<decisionNote>"
}
]
}
]
}GET /v1/scopes/{id}/policy#
A store's policy and pause state (workspace keys only)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/scopes/user-42/policy" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/policy`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"scopeId": "<scopeId>",
"stored": true,
"planCode": "<planCode>",
"tier": "free",
"trustTier": "red",
"rampStep": 1,
"reachCap": 1,
"effectiveReachCap": 1,
"fullReachCap": 1,
"quotas": {},
"monthlyQuota": {
"push": 1,
"email": 1,
"inapp": 1
},
"dailyMax": 1,
"effectiveDailyMax": 1,
"campaignsPerWeek": 1,
"allowedChannels": [
"push"
],
"frequencyCap": {},
"segmentCooldownHours": 1,
"contactAccess": "masked",
"status": "<status>",
"paused": true,
"pausedReason": "<pausedReason>",
"pausedAt": "<pausedAt>",
"updatedAt": "<updatedAt>",
"pausedBy": "<pausedBy>",
"updatedBy": "<updatedBy>"
}PUT /v1/scopes/{id}/policy#
Change a store's tier, trust tier, ramp step or overrides (workspace keys only); audited
Absent keys stay as they are; null clears a per-store override back to the tier's value.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
tier | "free" | "starter" | "growth" | "pro" | |
trustTier | "red" | "orange" | "yellow" | "green" | "official" | |
rampStep | 1 or 2 or 3 | |
reachCap | integer or null | min 1, max 100000 |
quotas | object or null | |
quotas.push | integer | min 0, max 10000 |
quotas.email | integer | min 0, max 10000 |
quotas.inapp | integer | min 0, max 10000 |
dailyMax | integer or null | min 0, max 1000 |
allowedChannels | "push" | "email" | "inapp"[] | up to 3 items |
reason | string | max 2000 |
curl -X PUT "$SAPAGAN_URL/v1/scopes/user-42/policy" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"tier": "free",
"trustTier": "red",
"rampStep": 1,
"reachCap": 1
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/policy`, {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"tier": "free",
"trustTier": "red",
"rampStep": 1,
"reachCap": 1
}),
});
const data = await res.json();Responses
{
"scopeId": "<scopeId>",
"stored": true,
"planCode": "<planCode>",
"tier": "free",
"trustTier": "red",
"rampStep": 1,
"reachCap": 1,
"effectiveReachCap": 1,
"fullReachCap": 1,
"quotas": {},
"monthlyQuota": {
"push": 1,
"email": 1,
"inapp": 1
},
"dailyMax": 1,
"effectiveDailyMax": 1,
"campaignsPerWeek": 1,
"allowedChannels": [
"push"
],
"frequencyCap": {},
"segmentCooldownHours": 1,
"contactAccess": "masked",
"status": "<status>",
"paused": true,
"pausedReason": "<pausedReason>",
"pausedAt": "<pausedAt>",
"updatedAt": "<updatedAt>",
"pausedBy": "<pausedBy>",
"updatedBy": "<updatedBy>"
}GET /v1/scopes/{id}/policy-audit#
A store's policy, pause and block history (workspace keys only)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
limit | query | integer | |
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/scopes/user-42/policy-audit" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/policy-audit`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"entries": [
{
"id": "user-42",
"action": "<action>",
"actor": "<actor>",
"reason": "Checked with the owner",
"before": null,
"after": null,
"occurredAt": "<occurredAt>"
}
]
}GET /v1/scopes/{id}/products#
Search one store's products (workspace keys and console sessions)
For the workspace's own campaigns: the store is named in the path and must be a store of this workspace (404 otherwise).
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
q | query | string | Words of the product's name, anywhere in it, any case. |
ids | query | string | Comma-separated listing ids (at most 50): exactly these, when they are the store's own and live. |
cursor | query | string | |
limit | query | integer | |
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/scopes/user-42/products" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/products`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"products": [
{
"id": "user-42",
"name": "order_placed",
"imageUrl": "<imageUrl>",
"price": 1,
"specialPrice": 1,
"stock": 1,
"sold": 1,
"updatedAt": "<updatedAt>"
}
],
"nextCursor": "<nextCursor>"
}POST /v1/scopes/{id}/unblock#
Lift a store's block (workspace keys only); audited
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
reason required | string | min 1, max 2000 |
curl -X POST "$SAPAGAN_URL/v1/scopes/user-42/unblock" \
-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/scopes/user-42/unblock`, {
method: "POST",
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
{
"id": "user-42",
"scopeId": "<scopeId>",
"category": "spam",
"reason": "Checked with the owner",
"startsAt": "<startsAt>",
"endsAt": "<endsAt>",
"permanent": true,
"createdBy": "<createdBy>",
"endedAt": "<endedAt>",
"endReason": "<endReason>",
"endedBy": "<endedBy>",
"endNote": "<endNote>"
}GET /v1/scopes/{id}/usage#
A store's campaign usage this calendar month (workspace keys only)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
at | query | string (date-time) | |
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/scopes/user-42/usage" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scopes/user-42/usage`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"scopeId": "<scopeId>",
"period": "<period>",
"timeZone": "<timeZone>",
"dailyMax": 1,
"channels": [
{
"channel": "push",
"used": 1,
"extra": 1,
"credits": 1,
"quota": 1,
"remaining": 1
}
]
}GET /v1/workspace/policy-defaults#
The workspace's policy settings: default trust tier, daily maxima by tier, seller ramp, appeals per block, block sets red, contact tiers (workspace keys only)
curl -X GET "$SAPAGAN_URL/v1/workspace/policy-defaults" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/workspace/policy-defaults`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"defaultTrustTier": "orange",
"tierDailyMax": {
"free": 1,
"starter": 1,
"growth": 1,
"pro": 1
},
"ramp": {
"1": {
"reach": 1,
"campaignsPerWeek": 0
},
"2": {
"reach": 1,
"campaignsPerWeek": 0
},
"3": {
"reach": 1,
"campaignsPerWeek": 0
}
},
"maxAppealsPerBlock": 1,
"blockSetsTrustRed": true,
"contactAccessTiers": [
"free"
],
"health": {
"windowDays": 1,
"unsubscribeAttributionHours": 1,
"rejectionWindowDays": 1,
"unsubscribePauseMinRevokers": 1,
"promotionMinCampaignSends": 1,
"thresholds": {
"complaint_rate": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"bounce_rate": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"unsubscribe_rate": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"invalid_token_rate": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"failure_rate": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"review_rejections": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"open_rate_drop": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
}
},
"promotion": {
"1": {
"campaigns": 1,
"minSent": 1,
"maxComplaintRate": 1,
"maxUnsubscribeRate": 1
},
"2": {
"campaigns": 1,
"minSent": 1,
"maxComplaintRate": 1,
"maxUnsubscribeRate": 1
}
},
"pauseDropsStep": true,
"pauseLowersTrust": true,
"pauseOfficial": true
}
}PUT /v1/workspace/policy-defaults#
Change the workspace's policy settings (workspace keys only); always with a reason; audited
Absent keys stay. Nothing is rewritten retroactively: lowering appeals per block keeps existing appeals; a new default trust tier applies only to stores whose trust tier was never set.
Request body
| Field | Type | Notes |
|---|---|---|
defaultTrustTier | "orange" | "yellow" | "green" | |
tierDailyMax | object | |
tierDailyMax.free | integer | min 0, max 1000 |
tierDailyMax.starter | integer | min 0, max 1000 |
tierDailyMax.growth | integer | min 0, max 1000 |
tierDailyMax.pro | integer | min 0, max 1000 |
ramp | object | |
ramp.1 | object | |
ramp.1.reach required | integer or null | min 1, max 100000 |
ramp.1.campaignsPerWeek required | integer or null | min 0, max 100 |
ramp.2 | object | |
ramp.2.reach required | integer or null | min 1, max 100000 |
ramp.2.campaignsPerWeek required | integer or null | min 0, max 100 |
ramp.3 | object | |
ramp.3.reach required | integer or null | min 1, max 100000 |
ramp.3.campaignsPerWeek required | integer or null | min 0, max 100 |
maxAppealsPerBlock | integer | min 0, max 20 |
blockSetsTrustRed | boolean | |
contactAccessTiers | "free" | "starter" | "growth" | "pro"[] | up to 4 items |
health | object | |
health.windowDays | integer | min 1, max 30 |
health.unsubscribeAttributionHours | integer | min 1, max 168 |
health.rejectionWindowDays | integer | min 1, max 90 |
health.unsubscribePauseMinRevokers | integer | min 1, max 100000 |
health.promotionMinCampaignSends | integer | min 1, max 100000 |
health.thresholds | object | |
health.thresholds.complaint_rate | object | |
health.thresholds.bounce_rate | object | |
health.thresholds.unsubscribe_rate | object | |
health.thresholds.invalid_token_rate | object | |
health.thresholds.failure_rate | object | |
health.thresholds.review_rejections | object | |
health.thresholds.open_rate_drop | object | |
health.promotion | object | |
health.promotion.1 | object | |
health.promotion.2 | object | |
health.pauseDropsStep | boolean | |
health.pauseLowersTrust | boolean | |
health.pauseOfficial | boolean | |
reason required | string | min 1, max 2000 |
curl -X PUT "$SAPAGAN_URL/v1/workspace/policy-defaults" \
-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/policy-defaults`, {
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
{
"defaultTrustTier": "orange",
"tierDailyMax": {
"free": 1,
"starter": 1,
"growth": 1,
"pro": 1
},
"ramp": {
"1": {
"reach": 1,
"campaignsPerWeek": 0
},
"2": {
"reach": 1,
"campaignsPerWeek": 0
},
"3": {
"reach": 1,
"campaignsPerWeek": 0
}
},
"maxAppealsPerBlock": 1,
"blockSetsTrustRed": true,
"contactAccessTiers": [
"free"
],
"health": {
"windowDays": 1,
"unsubscribeAttributionHours": 1,
"rejectionWindowDays": 1,
"unsubscribePauseMinRevokers": 1,
"promotionMinCampaignSends": 1,
"thresholds": {
"complaint_rate": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"bounce_rate": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"unsubscribe_rate": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"invalid_token_rate": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"failure_rate": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"review_rejections": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
},
"open_rate_drop": {
"watch": 1,
"pause": 1,
"minVolume": 1,
"pauseMinVolume": 1
}
},
"promotion": {
"1": {
"campaigns": 1,
"minSent": 1,
"maxComplaintRate": 1,
"maxUnsubscribeRate": 1
},
"2": {
"campaigns": 1,
"minSent": 1,
"maxComplaintRate": 1,
"maxUnsubscribeRate": 1
}
},
"pauseDropsStep": true,
"pauseLowersTrust": true,
"pauseOfficial": true
},
"changed": true
}