SapaganDocs sapagan.com

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.

Accepted keys Server key

Parameters

NameInTypeNotes
statusquery"ai_flagged" | "rejected" | "submitted"
scopeIdquerystring (uuid)
limitqueryinteger
curl -X GET "$SAPAGAN_URL/v1/review-queue" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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

Accepted keys Server key

Parameters

NameInTypeNotes
broadcastIdpathstring required
curl -X GET "$SAPAGAN_URL/v1/reviews/0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
broadcastIdpathstring required
curl -X GET "$SAPAGAN_URL/v1/reviews/0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b/email" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
broadcastIdpathstring required
curl -X GET "$SAPAGAN_URL/v1/reviews/0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b/image" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
broadcastIdpathstring required
curl -X GET "$SAPAGAN_URL/v1/reviews/0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b/images" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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)

Accepted keys Server key

curl -X GET "$SAPAGAN_URL/v1/workspace/review-settings" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "larkChatId": "<larkChatId>"
}

PUT /v1/workspace/review-settings#

Change the review settings (owner); audited with the reason

Accepted keys Server key

Request body

FieldTypeNotes
larkChatIdstring or nullmax 100
reason requiredstringmin 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"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden. Errors use the error body.

Example response 200

{
  "larkChatId": "<larkChatId>",
  "changed": true
}