Push

Push campaigns target either a segment or all users. Scheduled campaigns kick off a PUSH_CAMPAIGN workflow with startDelay so delivery fires at the intended time regardless of API uptime.

Endpoints

POST /admin/projects/:projectId/push/campaigns

Create a push campaign. If scheduled_at is provided, a workflow is started with the delay and the row is stored as scheduled; otherwise the row is draft.

Request

Local-time mode

When delivery_mode='local_time', local_date + local_time are interpreted in each recipient's timezone (recipients without one default to UTC). Amba groups recipients by timezone and fires one delivery per bucket so 09:00 in New York is genuinely 09:00 in New York. scheduled_at MUST be omitted — sending both returns 400 CONFLICTING_SCHEDULE. Conversely, local_date / local_time may not appear when delivery_mode='absolute'.

Response 201

{
  "data": {
    "id": "…",
    "name": "…",
    "title": "…",
    "body": "…",
    "data": {},
    "segment_id": null,
    "status": "scheduled",
    "scheduled_at": "…",
    "sent_at": null,
    "created_at": "…"
  }
}

If the workflow start fails, the row is transitioned to failed and the response reflects that (the handler never returns a stale scheduled).

Errors

• 400 INVALID_DELIVERY_MODE — delivery_mode is not absolute or local_time.
• 400 INVALID_SCHEDULED_AT — scheduled_at is not a parseable ISO-8601 string.
• 400 SCHEDULED_AT_IN_PAST — scheduled_at is already past.
• 400 INVALID_LOCAL_DATE — local_date is not a YYYY-MM-DD string (local_time mode).
• 400 INVALID_LOCAL_TIME — local_time is not an HH:MM[:SS] string (local_time mode).
• 400 CONFLICTING_SCHEDULE — mixing scheduled_at with localtime mode, or local* fields with absolute mode.
• 500 CREATE_FAILED.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/push/campaigns'

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/push/campaigns' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /admin/projects/:projectId/push/campaigns

List all campaigns for the project, newest first.

Response 200

{
  "data": [
    {
      "id": "…",
      "name": "…",
      "title": "…",
      "body": "…",
      "status": "sent",
      "scheduled_at": "…",
      "sent_at": "…",
      "stats": { "sent": 1200, "delivered": 1180, "opened": 340, "failed": 20 },
      "created_at": "…"
    }
  ]
}

Errors

• 500 LIST_FAILED.

Try it:

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/push/campaigns'

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/push/campaigns' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

GET /admin/projects/:projectId/push/campaigns/:campaignId

Fetch a single campaign.

Response 200

Same shape as an entry in the list response.

Errors

• 404 NOT_FOUND.
• 500 FETCH_FAILED.

Try it:

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/push/campaigns/%7B%7BcampaignId%7D%7D'

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/push/campaigns/{campaignId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

POST /admin/projects/:projectId/push/campaigns/:campaignId/send

Atomically transition status to sending and kick off the PUSH_CAMPAIGN workflow. Refuses to send a campaign that is already sending, sent, or scheduled (a scheduled campaign's delayed workflow is already queued).

Response 200

{ "data": { "status": "sending", "campaign_id": "…" } }

Errors

• 404 NOT_FOUND — campaign does not exist.
• 409 ALREADY_SCHEDULED — campaign is already scheduled; wait for it to fire or terminate the push-campaign-<campaignId> workflow in the the Amba support channel.
• 409 ALREADY_SENT — campaign is already sending or sent.
• 500 SEND_FAILED — workflow start failed; campaign rolled back to failed.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/push/campaigns/%7B%7BcampaignId%7D%7D/send'

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/push/campaigns/{campaignId}/send' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST /admin/projects/:projectId/push/campaigns/test

Send a one-off test push without creating a campaign. Exists so developers can verify APNs / FCM credentials.

Request

Response 200

{
  "data": {
    "sent": true,
    "delivery_id": "…",
    "provider": "apns",
    "provider_message_id": "…"
  }
}

Errors

• 400 INVALID_BODY — not valid JSON.
• 400 MISSING_TITLE / MISSING_BODY — required fields missing.
• 400 MISSING_TARGET — neither app_user_id nor device_token.
• 400 MISSING_PROVIDER — device_token set but provider missing.
• 404 NO_ACTIVE_TOKEN — app_user_id has no active push token.
• 400 NO_TOKEN — could not resolve a token.
• 502 SEND_FAILED / PUSH_FAILED — the push provider rejected the send. error.details includes delivery_id, provider, provider_message_id, invalid_token.
• 500 PUSH_TEST_FAILED.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/push/campaigns/test'

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/push/campaigns/test' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

PATCH /admin/projects/:projectId/push/campaigns/:campaignId

Update a campaign before send. Only draft and scheduled campaigns are mutable — anything past that (sending, sent, cancelled, failed) returns 409 ALREADY_SENT. If scheduled_at changes on a scheduled campaign, the existing workflow is terminated and re-started with the new startDelay so the campaign fires at the new time. Setting scheduled_at on a draft promotes it to scheduled.

At least one editable field must be supplied; otherwise the handler returns 400 EMPTY_UPDATE.

Request

Response 200

{
  "data": {
    "id": "…",
    "name": "…",
    "title": "…",
    "body": "…",
    "data": {},
    "segment_id": null,
    "status": "scheduled",
    "scheduled_at": "…",
    "updated_at": "…"
  }
}

Errors

• 400 INVALID_BODY — body is not JSON.
• 400 INVALID_DATA — data is not an object.
• 400 INVALID_SEGMENT_ID — segment_id is not a string or null.
• 400 INVALID_SCHEDULED_AT — scheduled_at is not a parseable ISO-8601 string.
• 400 SCHEDULED_AT_IN_PAST — scheduled_at is already past.
• 400 EMPTY_UPDATE — no editable fields supplied.
• 400 INVALID_CAMPAIGN_ID — campaignId is not a UUID.
• 404 NOT_FOUND — campaign does not exist.
• 409 ALREADY_SENT — campaign is past draft/scheduled (status is included in the message).
• 502 RESCHEDULE_FAILED — the row updated but the workflow could not be restarted; the campaign is rolled back to failed.
• 500 UPDATE_FAILED.

Try it:

curl -X PATCH 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/push/campaigns/%7B%7BcampaignId%7D%7D'

Curl:

curl -X PATCH '${BASE_URL}/admin/projects/{projectId}/push/campaigns/{campaignId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST /admin/projects/:projectId/users/:userId/push-schedule

Convenience wrapper for the most common scheduling case: "send one push to one user at one specific time." Amba creates an ephemeral system segment containing only userId and schedules a campaign targeted at that segment for delivery at fire_at, regardless of API uptime in the interim.

The created segment is named __user_<userId>_<campaignId> and flagged as system-internal so segment-list UIs can identify and skip it. Two scheduled pushes for the same user create two distinct segments + campaigns — there is no implicit dedupe.

When to use this vs. a regular campaign: if you need timezone-aware delivery (e.g. "fire at 9am in each user's local time"), use a regular POST /push/campaigns call with delivery_mode='local_time' instead. This endpoint is for absolute-time scheduling only.

On failure: if scheduling fails (or any step after the inserts errors), the ephemeral segment, its membership, and the campaign are deleted as compensation so no orphan __user_* segments accumulate.

Request

Response 201

{
  "data": {
    "campaign_id": "…",
    "segment_id": "…",
    "fire_at": "2026-05-12T13:00:00-05:00"
  }
}

Errors

• 400 INVALID_BODY — body is not JSON.
• 400 INVALID_FIRE_AT — fire_at is missing or not a parseable ISO-8601 string.
• 400 FIRE_AT_IN_PAST — fire_at is already past.
• 400 MISSING_TITLE / MISSING_BODY — required fields missing.
• 400 INVALID_DATA — data is not an object.
• 400 INVALID_USER_ID — userId is not a UUID.
• 404 USER_NOT_FOUND — userId does not exist in this project's your database.
• 500 SCHEDULE_FAILED — segment + campaign rolled back after a workflow-start (or other downstream) failure.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/users/%7B%7BuserId%7D%7D/push-schedule'

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/users/{userId}/push-schedule' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "fire_at": "2026-05-12T13:00:00-05:00",
    "title": "Reminder",
    "body": "Time to log today!",
    "data": { "deep_link": "amba://streak" }
  }'

DELETE /admin/projects/:projectId/push/campaigns/:campaignId

Cancel and hard-delete a campaign. Same ALREADY_SENT guard as PATCH — only draft and scheduled campaigns can be deleted. Any pending workflow is terminated as part of the delete; if the worker is unreachable the row is still removed (the orphaned workflow is logged as a warning).

Response 204

No body.

Errors

• 400 INVALID_CAMPAIGN_ID — campaignId is not a UUID.
• 404 NOT_FOUND — campaign does not exist.
• 409 ALREADY_SENT — campaign is past draft/scheduled.
• 500 DELETE_FAILED.

Try it:

curl -X DELETE 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/push/campaigns/%7B%7BcampaignId%7D%7D'

Curl:

curl -X DELETE '${BASE_URL}/admin/projects/{projectId}/push/campaigns/{campaignId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'