Neynar Notifications API

openapi: 3.2.0
info:
  contact:
    email: team@neynar.com
    name: Neynar
    url: https://neynar.com/
  description: The Neynar API allows you to interact with the Farcaster protocol among other things. See the [Neynar docs](https://docs.neynar.com/reference) for more details.
  title: Neynar Notifications API
  version: 3.176.0
servers:
- url: https://api.neynar.com
security:
- ApiKeyAuth: []
tags:
- description: Operations related to notifications
  externalDocs:
    description: More info about notifications
    url: https://docs.neynar.com/reference/notifications-operations
  name: Notifications
paths:
  /v2/farcaster/notifications/:
    get:
      description: Returns a list of notifications for a specific FID.
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-all-notifications
      operationId: fetch-all-notifications
      parameters:
      - $ref: '#/components/parameters/NeynarExperimentalHeader'
      - description: FID of the user you you want to fetch notifications for. The response will respect this user's mutes and blocks.
        in: query
        name: fid
        required: true
        schema:
          minimum: 1
          type: integer
      - description: Notification type to fetch. Comma separated values of follows, recasts, likes, mentions, replies.
        in: query
        name: type
        schema:
          items:
            enum:
            - follows
            - recasts
            - likes
            - mentions
            - replies
            - quotes
            type: string
          type: array
      - description: Number of results to fetch
        in: query
        name: limit
        schema:
          default: 15
          example: 15
          format: int32
          maximum: 25
          minimum: 1
          type: integer
        x-is-limit-param: true
      - description: Pagination cursor.
        in: query
        name: cursor
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationsResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
      summary: For user
      tags:
      - Notifications
  /v2/farcaster/notifications/channel/:
    get:
      description: Returns a list of notifications for a user in specific channels
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-channel-notifications-for-user
      operationId: fetch-channel-notifications-for-user
      parameters:
      - $ref: '#/components/parameters/NeynarExperimentalHeader'
      - description: FID of the user you you want to fetch notifications for. The response will respect this user's mutes and blocks.
        in: query
        name: fid
        required: true
        schema:
          minimum: 1
          type: integer
      - description: Comma separated channel_ids (find list of all channels here - https://docs.neynar.com/reference/list-all-channels)
        in: query
        name: channel_ids
        required: true
        schema:
          example: neynar,farcaster
          type: string
          x-comma-separated: true
      - description: Number of results to fetch
        in: query
        name: limit
        schema:
          default: 15
          example: 15
          format: int32
          maximum: 25
          minimum: 1
          type: integer
        x-is-limit-param: true
      - description: Pagination cursor.
        in: query
        name: cursor
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationsResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
      summary: For user by channel
      tags:
      - Notifications
  /v2/farcaster/notifications/parent_url/:
    get:
      description: Returns a list of notifications for a user in specific parent_urls
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-notifications-by-parent-url-for-user
      operationId: fetch-notifications-by-parent-url-for-user
      parameters:
      - $ref: '#/components/parameters/NeynarExperimentalHeader'
      - description: FID of the user you you want to fetch notifications for. The response will respect this user's mutes and blocks.
        in: query
        name: fid
        required: true
        schema:
          minimum: 1
          type: integer
      - description: Comma separated parent_urls
        in: query
        name: parent_urls
        required: true
        schema:
          example: chain://eip155:1/erc721:0xd4498134211baad5846ce70ce04e7c4da78931cc
          type: string
          x-comma-separated: true
      - description: Number of results to fetch
        in: query
        name: limit
        schema:
          default: 15
          example: 15
          format: int32
          maximum: 25
          minimum: 1
          type: integer
        x-is-limit-param: true
      - description: Pagination cursor.
        in: query
        name: cursor
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationsResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
      summary: For user by parent_urls
      tags:
      - Notifications
  /v2/farcaster/notifications/seen/:
    post:
      description: "Mark notifications as seen.\nYou can choose one of two authorization methods, either:\n  1. Provide a valid signer_uuid in the request body (Most common)\n  2. Provide a valid, signed \"Bearer\" token in the request's `Authorization` header similar to the\n     approach described [here](https://docs.farcaster.xyz/reference/warpcast/api#authentication)"
      externalDocs:
        url: https://docs.neynar.com/reference/mark-notifications-as-seen
      operationId: mark-notifications-as-seen
      parameters:
      - $ref: '#/components/parameters/AuthorizationHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkNotificationsAsSeenReqBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Mark as seen
      tags:
      - Notifications
components:
  schemas:
    FarcasterManifest:
      properties:
        account_association:
          $ref: '#/components/schemas/EncodedJsonFarcasterSignature'
        frame:
          properties:
            button_title:
              type: string
            description:
              description: Detailed description of the configuration
              type: string
            hero_image_url:
              description: URL of the hero image displayed for the configuration
              format: uri
              type: string
            home_url:
              type: string
            icon_url:
              type: string
            image_url:
              type: string
            name:
              type: string
            noindex:
              description: Whether search engines should not index this configuration
              type: boolean
            og_description:
              description: Description used for Open Graph previews
              type: string
            og_image_url:
              description: Image URL used for Open Graph previews
              format: uri
              type: string
            og_title:
              description: Title used for Open Graph previews
              type: string
            primary_category:
              description: Primary category the configuration belongs to
              type: string
            screenshot_urls:
              description: URLs of screenshots showcasing the configuration
              items:
                format: uri
                type: string
              type: array
            splash_background_color:
              type: string
            splash_image_url:
              type: string
            subtitle:
              description: Short subtitle for the configuration
              type: string
            tagline:
              description: Short tagline for the configuration
              type: string
            tags:
              description: Tags associated with the configuration
              items:
                type: string
              type: array
            version:
              enum:
              - '1'
              - 0.0.0
              - 0.0.1
              - next
              type: string
            webhook_url:
              type: string
          required:
          - version
          - name
          - home_url
          - icon_url
          type: object
        miniapp:
          properties:
            button_title:
              type: string
            description:
              description: Detailed description of the configuration
              type: string
            hero_image_url:
              description: URL of the hero image displayed for the configuration
              format: uri
              type: string
            home_url:
              type: string
            icon_url:
              type: string
            image_url:
              type: string
            name:
              type: string
            noindex:
              description: Whether search engines should not index this configuration
              type: boolean
            og_description:
              description: Description used for Open Graph previews
              type: string
            og_image_url:
              description: Image URL used for Open Graph previews
              format: uri
              type: string
            og_title:
              description: Title used for Open Graph previews
              type: string
            primary_category:
              description: Primary category the configuration belongs to
              type: string
            screenshot_urls:
              description: URLs of screenshots showcasing the configuration
              items:
                format: uri
                type: string
              type: array
            splash_background_color:
              type: string
            splash_image_url:
              type: string
            subtitle:
              description: Short subtitle for the configuration
              type: string
            tagline:
              description: Short tagline for the configuration
              type: string
            tags:
              description: Tags associated with the configuration
              items:
                type: string
              type: array
            version:
              enum:
              - '1'
              - 0.0.0
              - 0.0.1
              - next
              type: string
            webhook_url:
              type: string
          required:
          - version
          - name
          - home_url
          - icon_url
          type: object
      required:
      - account_association
      title: FarcasterManifest
      type: object
    TextRange:
      properties:
        end:
          minimum: 0
          type: number
        start:
          minimum: 0
          type: number
      required:
      - start
      - end
      title: TextRange
      type: object
    Channel:
      properties:
        created_at:
          format: date-time
          type: string
        description:
          type: string
        description_mentioned_profiles:
          items:
            $ref: '#/components/schemas/UserDehydrated'
          type: array
        description_mentioned_profiles_ranges:
          description: Positions within the text (inclusive start, exclusive end) where each mention occurs.
          items:
            $ref: '#/components/schemas/TextRange'
          type: array
        external_link:
          description: Channel's external link.
          properties:
            title:
              type: string
            url:
              type: string
          type: object
        follower_count:
          description: Number of followers the channel has.
          type: number
        hosts:
          deprecated: true
          items:
            $ref: '#/components/schemas/User'
          type: array
        id:
          type: string
        image_url:
          type: string
        lead:
          $ref: '#/components/schemas/User'
        member_count:
          format: int32
          type: integer
        moderator:
          allOf:
          - $ref: '#/components/schemas/User'
          deprecated: true
          description: Use `lead` instead.
        moderator_fids:
          items:
            $ref: '#/components/schemas/Fid'
          type: array
        name:
          type: string
        object:
          enum:
          - channel
          type: string
        parent_url:
          format: uri
          type: string
        pinned_cast_hash:
          example: '0x71d5225f77e0164388b1d4c120825f3a2c1f131c'
          pattern: ^(0x)?[a-fA-F0-9]{40}$
          type: string
        url:
          type: string
        viewer_context:
          $ref: '#/components/schemas/ChannelUserContext'
      required:
      - id
      - url
      - object
      - created_at
      title: Channel
      type: object
    ReactionWithUserInfo:
      properties:
        cast:
          $ref: '#/components/schemas/CastDehydrated'
        object:
          enum:
          - likes
          - recasts
          type: string
        user:
          $ref: '#/components/schemas/User'
      required:
      - object
      - cast
      - user
      title: ReactionWithUserInfo
      type: object
    Cast:
      properties:
        app:
          allOf:
          - $ref: '#/components/schemas/UserDehydrated'
        author:
          $ref: '#/components/schemas/User'
        author_channel_context:
          $ref: '#/components/schemas/ChannelUserContext'
        channel:
          allOf:
          - $ref: '#/components/schemas/ChannelOrChannelDehydrated'
        embeds:
          items:
            $ref: '#/components/schemas/Embed'
          type: array
        hash:
          type: string
        mentioned_channels:
          items:
            $ref: '#/components/schemas/ChannelDehydrated'
          type: array
        mentioned_channels_ranges:
          description: 'Positions within the text (inclusive start, exclusive end) where each mention occurs.

            Each index within this list corresponds to the same-numbered index in the mentioned_channels list.'
          items:
            $ref: '#/components/schemas/TextRange'
          type: array
        mentioned_profiles:
          items:
            $ref: '#/components/schemas/User'
          type: array
        mentioned_profiles_ranges:
          description: 'Positions within the text (inclusive start, exclusive end) where each mention occurs.

            Each index within this list corresponds to the same-numbered index in the mentioned_profiles list.'
          items:
            $ref: '#/components/schemas/TextRange'
          type: array
        object:
          enum:
          - cast
          type: string
        parent_author:
          properties:
            fid:
              allOf:
              - $ref: '#/components/schemas/Fid'
          required:
          - fid
          type: object
        parent_hash:
          type:
          - string
          - 'null'
        parent_url:
          type:
          - string
          - 'null'
        reactions:
          $ref: '#/components/schemas/CastReactions'
        replies:
          $ref: '#/components/schemas/CastReplies'
        root_parent_url:
          type:
          - string
          - 'null'
        text:
          type: string
        thread_hash:
          type:
          - string
          - 'null'
        timestamp:
          format: date-time
          type: string
        type:
          $ref: '#/components/schemas/CastNotificationType'
        viewer_context:
          $ref: '#/components/schemas/CastViewerContext'
      required:
      - object
      - hash
      - parent_hash
      - parent_url
      - root_parent_url
      - parent_author
      - author
      - text
      - timestamp
      - embeds
      - reactions
      - replies
      - thread_hash
      - mentioned_profiles
      - mentioned_profiles_ranges
      - mentioned_channels
      - mentioned_channels_ranges
      - channel
      title: Cast
      type: object
    MarkNotificationsAsSeenReqBody:
      properties:
        signer_uuid:
          description: The UUID of a signer with at least one write permission.  Required unless a valid Authorization Bearer token is provided in the header.
          type: string
        type:
          $ref: '#/components/schemas/NotificationType'
      title: MarkNotificationsAsSeenReqBody
      type: object
    CastId:
      deprecated: true
      description: '[DEPRECATED: Use "cast" key instead]'
      properties:
        fid:
          $ref: '#/components/schemas/Fid'
        hash:
          type: string
      required:
      - fid
      - hash
      title: CastId
      type: object
    ReactionLike:
      properties:
        fid:
          $ref: '#/components/schemas/Fid'
        fname:
          type: string
      required:
      - fid
      - fname
      title: ReactionLike
      type: object
    EmbedUrl:
      properties:
        metadata:
          $ref: '#/components/schemas/EmbedUrlMetadata'
        url:
          type: string
      required:
      - url
      title: EmbedUrl
      type: object
    ChannelMemberRole:
      description: The role of a channel member
      enum:
      - member
      - moderator
      - owner
      title: ChannelMemberRole
      type: string
    ErrorRes:
      description: Details for the error response
      properties:
        code:
          type: string
        message:
          type: string
        property:
          type: string
        status:
          format: int32
          type: integer
      required:
      - message
      title: ErrorRes
      type: object
    FrameActionButton:
      properties:
        action_type:
          $ref: '#/components/schemas/FrameButtonActionType'
        index:
          description: Index of the button
          type: integer
        post_url:
          description: Used specifically for the tx action type to post a successful transaction hash
          type: string
        target:
          description: Target of the button
          type: string
        title:
          description: Title of the button
          type: string
      required:
      - index
      - action_type
      title: FrameActionButton
      type: object
    VideoObject:
      properties:
        height:
          type: string
        type:
          type: string
        url:
          type: string
        width:
          type: string
      required:
      - url
      title: VideoObject
      type: object
    FrameV1:
      description: Mini app v1 object
      properties:
        buttons:
          items:
            $ref: '#/components/schemas/FrameActionButton'
          type: array
        frames_url:
          description: Launch URL of the mini app
          type: string
        image:
          description: URL of the image
          type: string
        image_aspect_ratio:
          type: string
        input:
          properties:
            text:
              description: Input text for the mini app
              type: string
          type: object
        post_url:
          description: Post URL to take an action on this mini app
          type: string
        state:
          properties:
            serialized:
              description: State for the mini app in a serialized format
              type: string
          type: object
        title:
          type: string
        version:
          description: Version of the mini app, 'next' for v2, 'vNext' for v1
          type: string
      required:
      - version
      - image
      - frames_url
      title: FrameV1
      type: object
    NotificationType:
      description: The type of notification to mark as seen. If not provided, all notifications will be marked as seen.
      enum:
      - follows
      - recasts
      - likes
      - mentions
      - replies
      - quotes
      title: NotificationType
      type: string
    CastEmbedded:
      properties:
        app:
          allOf:
          - $ref: '#/components/schemas/UserDehydrated'
        author:
          $ref: '#/components/schemas/UserDehydrated'
        channel:
          allOf:
          - $ref: '#/components/schemas/ChannelDehydrated'
        embeds:
          items:
            $ref: '#/components/schemas/EmbedDeep'
          type: array
        hash:
          type: string
        parent_author:
          properties:
            fid:
              allOf:
              - $ref: '#/components/schemas/Fid'
          required:
          - fid
          type: object
        parent_hash:
          type:
          - string
          - 'null'
        parent_url:
          type:
          - string
          - 'null'
        root_parent_url:
          type:
          - string
          - 'null'
        text:
          type: string
        timestamp:
          format: date-time
          type: string
      required:
      - hash
      - parent_hash
      - parent_url
      - root_parent_url
      - parent_author
      - author
      - text
      - timestamp
      - embeds
      - channel
      title: CastEmbedded
      type: object
    EmbedCastDeep:
      properties:
        cast:
          $ref: '#/components/schemas/CastDehydrated'
        cast_id:
          $ref: '#/components/schemas/CastId'
      required:
      - cast
      title: EmbedCastDeep
      type: object
    Location:
      description: Coordinates and place names for a location
      properties:
        address:
          $ref: '#/components/schemas/LocationAddress'
        latitude:
          format: double
          maximum: 90
          minimum: -90
          type: number
        longitude:
          format: double
          maximum: 180
          minimum: -180
          type: number
        radius:
          description: The radius in meters for the location search. Any location within this radius will be returned.
          minimum: 0
          type: number
      required:
      - latitude
      - longitude
      title: Location
      type: object
    ChannelOrChannelDehydrated:
      discriminator:
        mapping:
          channel: '#/components/schemas/Channel'
          channel_dehydrated: '#/components/schemas/ChannelDehydrated'
        propertyName: object
      oneOf:
      - $ref: '#/components/schemas/Channel'
      - $ref: '#/components/schemas/ChannelDehydrated'
      title: ChannelOrChannelDehydrated
      type: object
    OperationResponse:
      properties:
        message:
          type: string
        success:
          type: boolean
      title: OperationResponse
      type: object
    Frame:
      anyOf:
      - $ref: '#/components/schemas/FrameV1'
      - $ref: '#/components/schemas/FrameV2'
      discriminator:
        mapping:
          '1': '#/components/schemas/FrameV2'
          0.0.0: '#/components/schemas/FrameV2'
          0.0.1: '#/components/schemas/FrameV2'
          next: '#/components/schemas/FrameV2'
          vNext: '#/components/schemas/FrameV1'
        propertyName: version
      title: Frame
    CastViewerContext:
      description: Adds context on interactions the viewer has made with the cast.
      properties:
        liked:
          description: Indicates if the viewer liked the cast.
          type: boolean
        recasted:
          description: Indicates if the viewer recasted the cast.
          type: boolean
      required:
      - liked
      - recasted
      title: CastViewerContext
      type: object
    CastNotificationType:
      description: The notification type of a cast.
      enum:
      - cast-mention
      - cast-reply
      title: CastNotificationType
      type: string
    Follower:
      properties:
        app:
          $ref: '#/components/schemas/UserDehydrated'
        object:
          enum:
          - follower
          type: string
        user:
          $ref: '#/components/schemas/User'
      required:
      - object
      - user
      title: Follower
      type: object
    UserViewerContext:
      description: Adds context on the viewer's follow relationship with the user.
      properties:
        blocked_by:
          description: Indicates if the viewer is blocked by the user.
          type: boolean
        blocking:
          description: Indicates if the viewer is blocking the user.
          type: boolean
        followed_by:
          description: Indicates if the viewer is followed by the user.
          type: boolean
        following:
          description: Indicates if the viewer is following the user.
          type: boolean
      required:
      - following
      - followed_by
      - blocking
      - blocked_by
      title: UserViewerContext
      type: object
    SolAddress:
      description: Solana address
      pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
      title: SolAddress
      type: string
    ChannelUserContext:
      description: Adds context on the viewer's or author's role in the channel.
      properties:
        following:
          description: Indicates if the user is following the channel.
          type: boolean
        role:
          $ref: '#/components/schemas/ChannelMemberRole'
      required:
      - following
      title: ChannelUserContext
      type: object
    FrameV2:
      description: Mini app v2 object
      properties:
        author:
          $ref: '#/components/schemas/UserDehydrated'
        frames_url:
          description: Launch URL of the mini app
          type: string
        image:
          description: URL of the image
          type: string
        manifest:
          $ref: '#/components/schemas/FarcasterManifest'
        metadata:
          properties:
            html:
              $ref: '#/components/schemas/HtmlMetadata'
          required:
          - html
          type: object
        title:
          description: Button title of a mini app
          type: string
        version:
          description: Version of the mini app, 'next' for v2, 'vNext' for v1
          type: string
      required:
      - version
      - image
      - frames_url
      title: FrameV2
      type: object
    ImageObject:
      properties:
        alt:
          type: string
        height:
          type: string
        type:
          type: string
        url:
          type: string
        width:
          type: string
      required:
      - url
      title: ImageObject
      type: object
    UserDehydrated:
      properties:
        custody_address:
          $ref: '#/components/schemas/EthAddress'
        display_name:
          type:
          - string
          - 'null'
        fid:
          $ref: '#/components/schemas/Fid'
        object:
          enum:
          - user_dehydrated
          type: string
        pfp_url:
          type:
          - string
          - 'null'
        score:
          type: number
        username:
          type: string
      required:
      - object
      - fid
      title: UserDehydrated
      type: object
    EmbedDeep:
      anyOf:
      - $ref: '#/components/schemas/EmbedCastDeep'
      - $ref: '#/components/schemas/EmbedUrl'
      title: EmbedDeep
    EmbedUrlMetadata:
      properties:
        _status:
          type: string
        content_length:
          type:
          - integer
          - 'null'
        content_type:
          type:
          - string
          - 'null'
        frame:
          $ref: '#/components/schemas/Frame'
        html:
          $ref: '#/components/schemas/HtmlMetadata'
        image:
          properties:
            height_px:
              type: integer
            width_px:
              type: integer
          type: object
        video:
          properties:
            duration_s:
              type: number
            stream:
              items:
                properties:
                  codec_name:
                    type: string
                  height_px:
                    type: integer
                  width_px:
                    type: integer
                type: object
              type: array
          type: object
      required:
      - _status
      title: EmbedUrlMetadata
      type: object
    OembedRichData:
      description: Rich OEmbed data
      properties:
        author_name:
          description: The name of the author/owner of the resource.
          type:
          - string
          - 'null'
        author_url:
          description: A URL for the author/owner of the resource.
          type:
          - string
          - 'null'
        cache_age:
          description: The suggested cache lifetime for this resource, in seconds. Consumers may choose to use this value or not.
          type:
          - string
          - 'null'
        height:
          description: The height in pixels required to display the HTML.
          type:
          - number
          - 'null'
        html:
          description: The HTML required to display the resource. The HTML should have no padding or margins. Consumers may wish to load the HTML in an off-domain iframe to avoid XSS vulnerabilities. The markup should be valid XHTML 1.0 Basic.
          type:
          - string
          - 'null'
        provider_name:
          description: The name of the resource provider.
          type:
          - string
          - 'null'
        provider_url:
          description: The url of the resource provider.
          type:
          - string
          - 'null'
        thumbnail_height:
          description: The height of the optional thumbnail. If this parameter is present, thumbnail_url and thumbnail_width must also be present.
          type:
          - number
          - 'null'
        thumbnail_url:
          description: A URL to a thumbnail image representing the resource. The thumbnail must respect any maxwidth and maxheight parameters. If this parameter is present, thumbnail_width and thumbnail_height must also be present.
          type:
          - string
          - 'null'
        thumbnail_width:
          description: The width of the optional thumbnail. If this parameter is present, thumbnail_url and thumbnail_height must also be present.
          type:
          - number
          - 'null'
        title:
          description: A text title, describing the resource.
          type:
          - string
          - 'null'
        type:
          enum:
          - rich
          type: string
        version:
          type:
          - string
          - 'null'
        width:
          description: The width in pixels required to display the HTML.
          type:
          - number
          - 'null'
      required:
      - type
      - version
      - html
      title: OembedRichData
      type: object
    OembedPhotoData:
      description: Photo OEmbed data
      properties:
        author_name:
          description: The name of the author/owner of the resource.
          type:
          - string
          - 'null'
        author_url:
          description: A URL for the author/owner of the resource.
          type:
          - string
          - 'null'
        cache_age:
          description: The suggested cache lifetime for this resource, in seconds. Consumers may choose to use this value or not.
          type:
          - string
          - 'nu

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/neynar/refs/heads/main/openapi/neynar-notifications-api-openapi.yml