peskybird
API reference › Sending

Check a send

GEThttps://peskybird.app/api/push/sends/{id}
Auth App token

What happened to a message you sent: how many devices it was handed to, and how many the push service accepted.

For a message on a topic the token may send to. With deferred fan-out, poll until complete.

Path parameters

  • idstringRequired

    ULID: 26 Crockford base32 characters, lexically sortable. Message ids double as the sync cursor.

Response 200

The message and its counts.

  • messageobjectRequired

    A stored notification. id is the sync cursor.

    Fields (15)
    • idstringRequired

      Message id; also the sync cursor.

    • topicIdstringRequired

      ULID: 26 Crockford base32 characters, lexically sortable. Message ids double as the sync cursor.

    • topicNamestringRequired

      Topic name, unique per server: lowercase letters and digits in groups joined by single hyphens (like home-automation), 1 to 32 characters.

      at most 32 characters
    • titlestring

      Shown above the body.

      at most 256 characters
    • bodystringRequired

      The message text; Markdown when format is markdown.

      at most 2048 characters
    • prioritylow | normal | high | criticalRequired

      Platform-neutral priority; each transport maps it to its own levels. Closed enum.

    • urlURL

      Opened on tap.

      at most 2048 characters
    • actionsobject[]

      Buttons shown with the notification.

      at most 4 items
      Fields of each item (3)
      • idstringRequired

        Stable action identifier chosen by the publisher.

        at most 32 characters
      • titlestringRequired

        Button label.

        at most 64 characters
      • urlURL

        Opened when the action is tapped.

        at most 2048 characters
    • dataobject (string values)

      Opaque string map passed through to the client. At most 16 keys and 1024 bytes serialized. Keys starting with _ are reserved for the server and rejected on input.

      at most 16 keys
    • createdAtdate-timeRequired

      RFC 3339 / ISO 8601 timestamp with offset; UTC recommended.

    • expiresAtdate-time

      RFC 3339 / ISO 8601 timestamp with offset; UTC recommended.

    • formattext | markdown

      How body is rendered. markdown is a subset of CommonMark; the notification shows its plain text. Absent means text. Closed enum.

    • imageURL

      HTTPS URL of an image the phone downloads itself, at most 2048 chars. The server stores the URL and never fetches it.

      at most 2048 characters
    • sentByTokenIdstring

      Id of the app token that published the message; absent for server-originated messages.

    • replacesstring

      Set by the sender: this message takes the place of earlier messages on the same topic with the same key.

      at most 32 characters
  • recipientsinteger

    Devices the message was handed to. Absent for messages sent before servers recorded it.

  • sentintegerRequired

    Devices the push service accepted the message for.

  • failedintegerRequired

    Devices it could not be delivered to.

  • skippedintegerRequired

    Devices that were not tried: expired before delivery, or no transport for them.

  • completebooleanRequired

    True once every recipient has a result. A failed attempt may still be retried.

Errors

401unauthorized: The Authorization header is missing, or the token is not valid or has been revoked.
403forbidden: The token may not send to this topic, or the account does not allow what was asked. details.reason says which: topic_limit, images_not_enabled or account_suspended.
404not_found: No such endpoint. Usually a typo in the path or the wrong base URL.
429rate_limited: The account reached its daily limit, or the token sent too fast.

Every error uses the same envelope. Error format and codes