API reference
Approval
The review queue and what reviewers decided.
The review queue and what reviewers decided.
GET /v1/review-queue#
Broadcasts waiting for a person, oldest first
status is ai_flagged (default: held for a person), rejected (a person may override an AI rejection) or submitted (still with the AI). Workspace keys and operator sessions; store credentials are 403.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
status | query | "ai_flagged" | "rejected" | "submitted" | |
scopeId | query | string (uuid) | |
limit | query | integer |
curl -X GET "$SAPAGAN_URL/v1/review-queue" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/review-queue`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"items": [
{
"broadcast": {
"id": "user-42",
"scopeId": "<scopeId>",
"name": "order_placed",
"channel": "<channel>",
"templateId": "<templateId>",
"status": "draft",
"statusReason": "<statusReason>",
"requiresApproval": true,
"marketing": true,
"approvedAt": "<approvedAt>",
"contentUpdatedAt": "<contentUpdatedAt>",
"contentVersion": 1,
"scheduledFor": "<scheduledFor>",
"sendAtRequested": "<sendAtRequested>",
"recipientCount": 1,
"createdVia": "<createdVia>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
},
"store": {
"id": "user-42",
"name": "order_placed",
"trustTier": "red"
},
"aiReview": {
"id": "user-42",
"kind": "ai",
"reviewerId": "<reviewerId>",
"verdict": "<verdict>",
"confidence": 1,
"flags": [
"<flags>"
],
"reason": "Checked with the owner",
"promptVersion": "<promptVersion>",
"model": "<model>",
"contentVersion": 1,
"imageSha256": "<imageSha256>",
"createdAt": "<createdAt>"
},
"waitingSince": "<waitingSince>"
}
]
}GET /v1/reviews/{broadcastId}#
A broadcast with its history and every review of it
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
broadcastId | path | string required |
curl -X GET "$SAPAGAN_URL/v1/reviews/0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/reviews/0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"broadcast": {
"id": "user-42",
"scopeId": "<scopeId>",
"name": "order_placed",
"channel": "<channel>",
"templateId": "<templateId>",
"content": null,
"audience": null,
"status": "draft",
"statusReason": "<statusReason>",
"requiresApproval": true,
"marketing": true,
"approvedAt": "<approvedAt>",
"contentUpdatedAt": "<contentUpdatedAt>",
"contentVersion": 1,
"scheduledFor": "<scheduledFor>",
"sendAtRequested": "<sendAtRequested>",
"recipientCount": 1,
"goal": null,
"createdVia": "<createdVia>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"approvedBy": "<approvedBy>",
"createdBy": "<createdBy>",
"recipientHash": "<recipientHash>"
},
"history": [
{
"event": "<event>",
"fromStatus": "<fromStatus>",
"toStatus": "<toStatus>",
"note": "Looks good",
"detail": null,
"at": "<at>",
"actor": "<actor>"
}
],
"reviews": [
{
"id": "user-42",
"kind": "ai",
"reviewerId": "<reviewerId>",
"verdict": "<verdict>",
"confidence": 1,
"flags": [
"<flags>"
],
"reason": "Checked with the owner",
"promptVersion": "<promptVersion>",
"model": "<model>",
"contentVersion": 1,
"imageSha256": "<imageSha256>",
"createdAt": "<createdAt>"
}
],
"authors": [
"<authors>"
]
}GET /v1/reviews/{broadcastId}/email#
An email campaign under review, rendered as the send renders it (P2-10)
The broadcast's email (a store's or the workspace's own) with its owner's rules, its pinned layout, the engine's footer and the store's own products, for no one in particular (no buyer attributes) and with sample footer links. A problem is valid: false with errors. 404 when the broadcast is not an email.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
broadcastId | path | string required |
curl -X GET "$SAPAGAN_URL/v1/reviews/0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b/email" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/reviews/0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b/email`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"valid": true,
"errors": [
{
"field": "<field>",
"code": "<code>",
"message": "<message>"
}
],
"email": {
"subject": "<subject>",
"preheader": "<preheader>",
"html": "<html>",
"text": "<text>",
"sizeBytes": 1
}
}GET /v1/reviews/{broadcastId}/image#
The campaign's image as Sapagan fetches it, with its SHA-256 (for the reviewer)
Fetched from the allowlisted host now, at most 2 MB, so the reviewer sees the bytes an approval binds to (imageSha256). 404 when the campaign has no image; 409 image_unavailable when it cannot be fetched.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
broadcastId | path | string required |
curl -X GET "$SAPAGAN_URL/v1/reviews/0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b/image" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/reviews/0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b/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/reviews/{broadcastId}/images#
Every picture of a campaign as Sapagan fetches it, and the digest an approval binds to (P2-10)
For an email: each picture (image blocks, row backgrounds, an HTML block's images) in document order, then its product cards' photos as the store's catalogue has them now (productPhoto), each fetched from its allowlisted host now (at most 2 MB each, at most 40 in all), and digest, the SHA-256 an approval sends as imageSha256. A push or in-app message: its one image, digest its SHA-256. 404 when the campaign has no picture and no product card; 409 image_unavailable when one cannot be fetched, the catalogue cannot be read, or there are too many.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
broadcastId | path | string required |
curl -X GET "$SAPAGAN_URL/v1/reviews/0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b/images" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/reviews/0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b/images`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"images": [
{
"url": "https://example.com",
"contentType": "<contentType>",
"sha256": "<sha256>",
"size": 1,
"dataBase64": "<dataBase64>",
"productPhoto": true
}
],
"digest": "<digest>"
}GET /v1/workspace/review-settings#
The workspace's review settings (the Lark reviewer group)
curl -X GET "$SAPAGAN_URL/v1/workspace/review-settings" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/workspace/review-settings`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"larkChatId": "<larkChatId>"
}PUT /v1/workspace/review-settings#
Change the review settings (owner); audited with the reason
Request body
| Field | Type | Notes |
|---|---|---|
larkChatId | string or null | max 100 |
reason required | string | min 3, max 2000 |
curl -X PUT "$SAPAGAN_URL/v1/workspace/review-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/review-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
{
"larkChatId": "<larkChatId>",
"changed": true
}