Skip to main content
POST
/
v2
/
farcaster
/
frame
/
notifications
Send notifications
curl --request POST \
  --url https://api.neynar.com/v2/farcaster/frame/notifications/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "notification": {
    "title": "New Message",
    "body": "You have received a new message in your inbox.",
    "target_url": "https://example.com/notifications",
    "uuid": "123e4567-e89b-12d3-a456-426614174000"
  },
  "target_fids": [
    1,
    2,
    3
  ],
  "filters": {
    "exclude_fids": [
      3
    ],
    "following_fid": 3,
    "minimum_user_score": 0.5,
    "near_location": {
      "latitude": 0,
      "longitude": 0,
      "address": {
        "city": "<string>",
        "country": "<string>",
        "state": "<string>",
        "state_code": "<string>",
        "country_code": "<string>"
      },
      "radius": 1
    }
  }
}
'
{
  "campaign_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "success_count": 123,
  "failure_count": 123,
  "not_attempted_count": 123,
  "retryable_fids": [
    3
  ]
}

​
See guide on setting this up easily Send Notifications to Mini App Users

​
Node.js SDK

🔗 SDK Method: publishFrameNotifications Use this API endpoint with the Neynar Node.js SDK for typed responses and better developer experience.

Authorizations

​
x-api-key
string
header
default:NEYNAR_API_DOCS
required

API key to authorize requests

Body

application/json
​
notification
object
required
​
target_fids
integer[]

An array of target FIDs to whom the notifications should be sent. Each FID must be a positive integer. Pass an empty array to send notifications to all FIDs with notifications enabled for the mini app.

Maximum array length: 100
Required range: x >= 1
Example:
[1, 2, 3]
​
filters
object

Filters to apply to the target_fids set. All filters are additive, so only users matching all filters will be notified.

Response

Success

​
campaign_id
string<uuid>
required

The unique identifier for the notification campaign.

​
success_count
integer<int32> | null
required

The number of notifications successfully delivered.

​
failure_count
integer<int32> | null
required

The number of notifications that failed to deliver.

​
not_attempted_count
integer<int32> | null
required

The number of notifications not attempted (e.g., disabled tokens, invalid tokens).

​
retryable_fids
integer<int32>[]

List of FIDs that failed due to retryable errors (rate_limited, failed, http_error). Can be used to retry sending notifications to these users.

The unique identifier of a farcaster user or app (unsigned integer)

Required range: x >= 0