Docs menu

Notifications API · push

Push to the organization's own people

POST /push

Push to the organization's own people, never a customer: every active member holding one of audience.roles, or the members in audience.users (at most 50).

Each person with kind on is pushed on every device they registered — title, body, the page path opens and up to two actions, each opening its own page, where the person's session confirms it (a tap is no authorisation); quiet hours hold it till they end. Appends notifications.push-raised (who it reached, who not) and a notifications.requested per device, then notifications.sent or notifications.failed. Not held by read-only mode; free. 503 AudienceUnavailable when roles cannot be read. Keyed on reference: a retry answers the raise as recorded and pushes no one twice.

Access

Requires notifications:write.

How scopes come from roles: Scopes and roles. Getting a token: Authentication and app tokens.

Retries

Keyed on reference: a retry answers the raise as recorded and pushes no one twice.

A retry with the same key answers 200, with what the first call recorded.

Why every write carries a key: Idempotency and retries.

Facts appended

  • notifications.push-raised
  • notifications.requested
  • notifications.sent
  • notifications.failed

What a fact is: Facts and the journal.

AI agent tool

Agents call this as notifications_notify_members (Notifications: Push to people in the organization), in the notifications toolset.

Connecting an agent: AI agents.

Example

curl 
curl -X POST 'https://notifications.getmanifold.io/push' \
  -H "Authorization: Bearer $MANIFOLD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "reference": "margin-approval:apr_7f2a",
  "kind": "approval-request",
  "audience": {
    "roles": [
      "owner",
      "admin"
    ]
  },
  "title": "Approve a price below margin",
  "body": "Sam asks to sell 12 × Trail tent 2P at 14% margin (minimum 22%) on SO-19203.",
  "path": "/orders/ord_01a15a3c-7e21-7c4d-9b0e-5f6a7b8c9d0e?margin-approval=apr_7f2a",
  "actions": [
    {
      "id": "approve",
      "title": "Approve",
      "path": "/orders/ord_01a15a3c-7e21-7c4d-9b0e-5f6a7b8c9d0e?margin-approval=apr_7f2a&decide=approve"
    },
    {
      "id": "decline",
      "title": "Decline",
      "path": "/orders/ord_01a15a3c-7e21-7c4d-9b0e-5f6a7b8c9d0e?margin-approval=apr_7f2a&decide=decline"
    }
  ]
}'
JavaScript (fetch) 
const response = await fetch("https://notifications.getmanifold.io/push", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MANIFOLD_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "reference": "margin-approval:apr_7f2a",
    "kind": "approval-request",
    "audience": {
      "roles": [
        "owner",
        "admin"
      ]
    },
    "title": "Approve a price below margin",
    "body": "Sam asks to sell 12 × Trail tent 2P at 14% margin (minimum 22%) on SO-19203.",
    "path": "/orders/ord_01a15a3c-7e21-7c4d-9b0e-5f6a7b8c9d0e?margin-approval=apr_7f2a",
    "actions": [
      {
        "id": "approve",
        "title": "Approve",
        "path": "/orders/ord_01a15a3c-7e21-7c4d-9b0e-5f6a7b8c9d0e?margin-approval=apr_7f2a&decide=approve"
      },
      {
        "id": "decline",
        "title": "Decline",
        "path": "/orders/ord_01a15a3c-7e21-7c4d-9b0e-5f6a7b8c9d0e?margin-approval=apr_7f2a&decide=decline"
      }
    ]
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const answer = await response.json();
Request body · application/json 
{
  "reference": "margin-approval:apr_7f2a",
  "kind": "approval-request",
  "audience": {
    "roles": [
      "owner",
      "admin"
    ]
  },
  "title": "Approve a price below margin",
  "body": "Sam asks to sell 12 × Trail tent 2P at 14% margin (minimum 22%) on SO-19203.",
  "path": "/orders/ord_01a15a3c-7e21-7c4d-9b0e-5f6a7b8c9d0e?margin-approval=apr_7f2a",
  "actions": [
    {
      "id": "approve",
      "title": "Approve",
      "path": "/orders/ord_01a15a3c-7e21-7c4d-9b0e-5f6a7b8c9d0e?margin-approval=apr_7f2a&decide=approve"
    },
    {
      "id": "decline",
      "title": "Decline",
      "path": "/orders/ord_01a15a3c-7e21-7c4d-9b0e-5f6a7b8c9d0e?margin-approval=apr_7f2a&decide=decline"
    }
  ]
}
Response · 200 · application/json 
{
  "reference": "margin-approval:apr_7f2a",
  "kind": "approval-request",
  "notifications": [
    {
      "id": "ntf_01a15c42-6f7a-7b8c-9d0e-1f2a3b4c5d6e",
      "kind": "approval-request",
      "channel": "push",
      "status": "sent",
      "to": [
        "pdv_01a15c20-4d5e-7f6a-8b9c-0d1e2f3a4b5c"
      ],
      "cc": [],
      "from": "Manifold",
      "subject": "Approve a price below margin",
      "source": {
        "kind": "push",
        "id": "margin-approval:apr_7f2a"
      },
      "requestedBy": {
        "_tag": "user",
        "id": "usr_01a15709-7582-7646-b491-261a138f0650"
      },
      "requestedAt": "2026-10-29T01:13:00.000Z",
      "recipient": {
        "user": "usr_01a15c31-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
      },
      "push": {
        "body": "Sam asks to sell 12 × Trail tent 2P at 14% margin (minimum 22%) on SO-19203.",
        "path": "/orders/ord_01a15a3c-7e21-7c4d-9b0e-5f6a7b8c9d0e?margin-approval=apr_7f2a",
        "actions": [
          {
            "id": "approve",
            "title": "Approve",
            "path": "/orders/ord_01a15a3c-7e21-7c4d-9b0e-5f6a7b8c9d0e?margin-approval=apr_7f2a&decide=approve"
          },
          {
            "id": "decline",
            "title": "Decline",
            "path": "/orders/ord_01a15a3c-7e21-7c4d-9b0e-5f6a7b8c9d0e?margin-approval=apr_7f2a&decide=decline"
          }
        ]
      },
      "sentAt": "2026-10-29T01:13:01.000Z",
      "providerMessageId": "projects/manifold-508900/messages/0:1761700381000000%e2b7c1f9e2b7c1f9",
      "steps": [
        {
          "status": "requested",
          "at": "2026-10-29T01:13:00.000Z"
        },
        {
          "status": "sent",
          "at": "2026-10-29T01:13:01.000Z"
        }
      ]
    }
  ],
  "skipped": [
    {
      "userId": "usr_01a15c53-7a8b-7c9d-8e0f-2a3b4c5d6e7f",
      "reason": "no-device"
    }
  ]
}

The panel writes this call in other languages. It does not send it: Manifold's APIs do not take calls from a web page on another site, so run the call from your own code or terminal. The whole API as OpenAPI: notifications-manager.openapi.json. Base URL https://notifications.getmanifold.io.

Errors

Every refusal is a status and a JSON body whose _tag names it. A refused call changes nothing.

401

RefusalWhat it meansWhat to do
Unauthorized reason The token is missing, expired or not one Manifold issued.Get a fresh token and send the call again.
TokenAlreadyUsed tokenId A single-use app token was already spent.Mint a new token for this call.

402

RefusalWhat it meansWhat to do
SubscriptionRequired status The organization's subscription has lapsed, so writes are refused.An owner settles billing. Reads still work meanwhile.

403

RefusalWhat it meansWhat to do
TenantRequired userId The token names no organization.Choose the organization, then get a new token.
ScopeRequired required The token's roles do not grant the scope this call needs.Ask an owner or admin for a role that grants it.

409

RefusalWhat it meansWhat to do
MirroredFromSource source This area is fed by your source system until the organization goes live.Make the change in the source system, or go live first.

503

RefusalWhat it meansWhat to do
AudienceUnavailable reason Roles cannot be read.Send the same request again, with the same key.
RequestLogUnavailable tokenId, reason The service could not record the request, so it did nothing.Send the same request again, with the same key.

How refusals work everywhere: Errors.