---
title: "Queue a web push notification (what push.send calls)"
method: POST
path: "/projects/v1/{project_id}/push/messages"
tags: ["Projects"]
---

# Queue a web push notification (what push.send calls)

`POST /projects/v1/{project_id}/push/messages`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/projects/v1/{project_id}/push/messages`
- Auth: HTTP bearer

tenant-web-push. The project's own service key only (a function's `push.send`). Queues one delivery per targeted phone, before anything is sent, and counts them against the organization's daily cap (100 / 1,000 / 10,000 on prototype / hobby / team). A message that does not fit is refused whole. Not lifecycle-gated.

## Path parameters

- `project_id` string, required: Run402 project ID. Public IDs are not UUIDs.

## Request body

- PushSendRequest
  - `title` string, required
  - `body` string, nullable
  - `url` string, nullable: A path on the app, starting with `/` (default `/`), resolved against the origin each phone signed up on.
  - `tag` string, nullable: A newer message with the same tag replaces the older one on the phone.
  - `to` object, nullable: One end user's phones. Omit to reach every phone signed up to the project.
    - `user_id` string, uuid, required

## Response `200`

no_subscribers: nobody the message addresses has a phone signed up.

- PushSendResponse
  - `message_id` string, required
  - `status` 'queued' | 'no_subscribers', required
  - `devices` integer, required: Phones the message targets, each one delivery against the daily cap.
  - `next_actions` object[]

## Other responses

- `202`: Queued; poll the message for each phone's outcome.
- `400`: VALIDATION_FAILED, naming details.field.
- `401`: AUTH_REQUIRED: no valid service key.
- `403`: FORBIDDEN (another project's key) or QUOTA_EXCEEDED (details.resource push_deliveries_per_day, with the upgrade).
- `429`: RATE_LIMITED: the top tier's daily cap is used; Retry-After is the seconds until UTC midnight.

## Changes

- **2026-10-21** `cc6ccb110365`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/run402/apis/run402-api/changes/projects/v1/:project_id/push/messages/post.md)

---

[API](https://skmtc.dev/run402/apis/run402-api.md) · [All operations](https://skmtc.dev/run402/apis/run402-api/llms.txt) · [OpenAPI document](https://skmtc.dev/run402/apis/run402-api/revisions/cc6ccb110365?raw)