Blink Members API

openapi: 3.2.0
info:
  title: Blink Chat Members API
  version: 1.1.0
  description: 'The Blink Chat API lets integrations create and manage chats, control who has access to them and who is in them, and send, read, edit, react to and delete messages on behalf of an app.

    ## Concepts

    All calls are made from an **app identity**; every endpoint acts on behalf of that app.

    A **chat** is a **private** thread of communication: the users and apps individually granted access to it take part, and nobody else.

    **Access and membership are separate.** *Access* is permission to be in a chat, given by a **grant** and listed in the chat''s **grants** collection. *Membership* is whether a principal has actually joined: members appear in the chat''s member listing and the chat reaches their inbox.

    The two usually move together — granting a user or app access also joins them, and revoking it removes them — but membership can change on its own: a member may leave, or be removed by an administrator, while keeping their grant, and may then rejoin with `:join`.

    A **member** is a user or app currently in a chat. Each member carries their `role` (`admin` or `member`), their `membership` state, and `access_via`, the grant giving them access. The caller''s own row comes back with an `@type` of `me` and carries the favourite flag and inbox state that belong to them alone.

    A **message** carries a structured **body** (Markdown, and other variants), an optional set of file **attachments**, a **sender**, and any **reactions** recorded against it.

    **Attachments** - message files and chat icons are referenced by the id of an existing attachment. This API does not yet expose a way to upload attachments.

    ## Pagination

    List endpoints return a page of results together with a `page` object. To fetch the next page, pass the returned `next_cursor` value back in the `cursor` query parameter.

    ## Errors

    Errors are returned as RFC 9457 problem documents (`application/problem+json`) using the `ProblemDetail` schema.'
servers:
- url: https://api.joinblink.com/api/platform
  description: Production API. Replace with the base URL for your environment.
security:
- bearerAuth: []
tags:
- name: Members
  description: Manage the users and apps that are in a chat — joining, leaving, removing and roles.
paths:
  /chats/{chatId}/members:
    get:
      tags:
      - Members
      summary: List the members of a chat
      operationId: listMembers
      description: 'Returns a page of the principals who have joined the chat, ordered by display name. Somebody with access who has not joined does not appear — they are not a member — and nor does somebody who has left. Members in every inbox state do appear, including those who have archived the chat: archiving is private and does not remove anybody from the listing everybody else sees.

        Each row carries `access_via`, the grant by which that principal has access. The caller''s own row comes back with an `@type` of `me`, carrying the favourite flag and inbox state that belong to them alone; other users are `user` and apps are `app`. Supply the optional `type` query parameter to restrict results to a single principal type.'
      parameters:
      - $ref: '#/components/parameters/ChatId'
      - name: type
        in: query
        required: false
        description: If present, restricts results to members of this principal type.
        schema:
          type: string
          description: The type of entity backing a member.
          enum:
          - user
          - app
      - $ref: '#/components/parameters/Size'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorPageMember'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /chats/{chatId}/members/apps/{appIdentityId}:
    patch:
      tags:
      - Members
      summary: Update an app's role in a chat
      operationId: updateAppMemberRole
      description: 'Updates whether an app is an administrator of the chat. An app holds a role exactly as a user does, so a bot administers a chat on the same terms, and role is the only field an app has to update: it carries no read position, favourite flag or inbox state. `role` is required and the app must already be a member. Returns the updated member, always with an `@type` of `app`, since the variant follows the member updated rather than the caller. Supplying the role it already holds is a no-op that returns it unchanged.'
      parameters:
      - $ref: '#/components/parameters/ChatId'
      - $ref: '#/components/parameters/AppIdentityId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMemberRole'
      responses:
        '200':
          description: The updated member.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
      - Members
      summary: Remove an app from a chat
      operationId: removeAppMember
      description: 'Removes an app from the chat on the same terms as removing a user: its grant is untouched, so it keeps access and may rejoin. Returns the removed app''s row.'
      parameters:
      - $ref: '#/components/parameters/ChatId'
      - $ref: '#/components/parameters/AppIdentityId'
      responses:
        '200':
          description: The removed app's member row.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /chats/{chatId}/members/me:
    get:
      tags:
      - Members
      summary: Get the caller's own membership of a chat
      operationId: getMyMembership
      description: 'Returns the calling principal''s own row: why they have access, whether they have joined, their role, and — for a user — the favourite flag and inbox state that belong to them alone. Caller-scoped, so there is no reading somebody else''s row through it.'
      parameters:
      - $ref: '#/components/parameters/ChatId'
      responses:
        '200':
          description: The caller's own member row.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /chats/{chatId}/members/users/{userId}:
    patch:
      tags:
      - Members
      summary: Update a user's role in a chat
      operationId: updateUserMemberRole
      description: Updates whether a user is an administrator of the chat. `role` is required and the user must already be a member. Role attaches to membership rather than to the grant that justifies it, so it survives the user leaving and rejoining. Returns the updated member — `@type` of `me` when the user is the caller, otherwise `user`. Supplying the role they already hold is a no-op that returns them unchanged.
      parameters:
      - $ref: '#/components/parameters/ChatId'
      - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMemberRole'
      responses:
        '200':
          description: The updated member.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
      - Members
      summary: Remove a user from a chat
      operationId: removeUserMember
      description: Removes a user from the chat on an administrator's instruction, leaving their grant untouched — so they keep access and may rejoin with `:join`. Removing somebody and keeping them out means revoking their access as well. Returns the removed user's row.
      parameters:
      - $ref: '#/components/parameters/ChatId'
      - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: The removed user's member row.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
              example:
                '@type': user
                member_id:
                  chat_id: c-00000000-0000-0000-0000-000000000000
                  principal:
                    '@type': user
                    user_id: u-00000000-0000-0000-0000-000000000000
                display_name: Alice Smith
                access_via:
                - '@type': explicit
                membership: left
                role: member
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /chats/{chatId}:join:
    post:
      tags:
      - Members
      summary: Join a chat the caller has access to
      operationId: joinChat
      description: 'Joins the calling principal to the chat, so they are listed to the other members and it reaches their inbox. Requires access and never grants it: to bring somebody else in, grant them access instead. Its main use is rejoining a chat the caller previously left, which needs no new grant and restores the read position their retained row preserved. Joining a chat the caller is already in is a successful no-op. Returns the caller''s own row.'
      parameters:
      - $ref: '#/components/parameters/ChatId'
      responses:
        '200':
          description: The caller's own member row after joining.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /chats/{chatId}:leave:
    post:
      tags:
      - Members
      summary: Leave a chat, keeping access
      operationId: leaveChat
      description: 'Removes the calling principal from the chat while leaving their access untouched, so a caller with access may still read it and may rejoin at any time. Leaving is visible: the other members see the caller drop out of the listing. Leaving a chat the caller has already left is a successful no-op. Returns the caller''s own row.'
      parameters:
      - $ref: '#/components/parameters/ChatId'
      responses:
        '200':
          description: The caller's own member row after leaving.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    UserMember:
      type: object
      description: Another user in a chat, as seen by someone else in it. Carries the read position the rest of the chat may see; the user's own favourite flag and inbox state reach only them.
      required:
      - '@type'
      properties:
        '@type':
          type: string
          enum:
          - user
          example: user
        member_id:
          $ref: '#/components/schemas/MemberId'
        display_name:
          type: string
          description: The user's display name, projected from the user directory into the chat service and kept up to date via eventual consistency.
          example: Alice Smith
        access_via:
          type: array
          description: Every route by which the user has access.
          items:
            $ref: '#/components/schemas/AccessSource'
        membership:
          $ref: '#/components/schemas/Membership'
        role:
          $ref: '#/components/schemas/Role'
        read_up_to:
          $ref: '#/components/schemas/MessageId'
    ChatPrincipal:
      description: 'The ''who'' of a member: either a user or an automated app. Serialised with an `@type` discriminator.'
      oneOf:
      - $ref: '#/components/schemas/UserPrincipal'
      - $ref: '#/components/schemas/AppPrincipal'
      discriminator:
        propertyName: '@type'
        mapping:
          user: '#/components/schemas/UserPrincipal'
          app: '#/components/schemas/AppPrincipal'
    UserPrincipal:
      type: object
      description: A principal backed by a regular user.
      required:
      - '@type'
      - user_id
      properties:
        '@type':
          type: string
          enum:
          - user
          example: user
        user_id:
          type: string
          description: The underlying user.
          example: u-00000000-0000-0000-0000-000000000000
    Role:
      type: string
      description: The role of a member within a chat, which determines what management actions they are able to take on the chat.
      enum:
      - admin
      - member
    ProblemDetail:
      type: object
      additionalProperties: true
      description: An RFC 9457 problem document describing why the request failed.
      properties:
        type:
          type: string
          format: uri
          description: Identifies the problem type; `about:blank` when unclassified.
          example: about:blank
        title:
          type: string
          description: Short, human-readable summary of the problem type.
          example: Not Found
        status:
          type: integer
          format: int32
          description: The HTTP status code, repeated in the body.
          example: 404
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
          example: Not Found
        instance:
          type: string
          format: uri
          description: The path of the request that failed.
    CursorPageMember:
      type: object
      description: A page of members.
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/Member'
        page:
          $ref: '#/components/schemas/PageMetadata'
    Member:
      description: 'A principal in a chat, as one row of its member listing: why they have access, whether they have joined, what they may do, and — on their own row alone — where the chat sits in their client. Serialised with an `@type` discriminator naming the variant: `user` for another user, `app` for an automated app, and `me` for the caller''s own row.'
      oneOf:
      - $ref: '#/components/schemas/UserMember'
      - $ref: '#/components/schemas/AppMember'
      - $ref: '#/components/schemas/SelfMember'
      discriminator:
        propertyName: '@type'
        mapping:
          user: '#/components/schemas/UserMember'
          app: '#/components/schemas/AppMember'
          me: '#/components/schemas/SelfMember'
    PageMetadata:
      type: object
      description: Metadata describing a page of a cursor-paginated listing.
      properties:
        size:
          type: integer
          format: int64
          description: The number of items in this page.
        total_elements:
          type:
          - integer
          - 'null'
          format: int64
          description: Total number of items across all pages, when known; otherwise null.
        total_pages:
          type:
          - integer
          - 'null'
          format: int64
          description: Total number of pages, when known; otherwise null.
        has_next:
          type: boolean
          description: Whether a further page is available.
        next_cursor:
          type:
          - string
          - 'null'
          description: Opaque, base64-encoded cursor for the next page; null if there is none.
        prev_cursor:
          type:
          - string
          - 'null'
          description: Opaque, base64-encoded cursor for the previous page; null if there is none.
    AccessSource:
      description: Why a principal has access to a chat. A member carries these as a list. Serialised with an `@type` discriminator.
      oneOf:
      - $ref: '#/components/schemas/ExplicitAccessSource'
      discriminator:
        propertyName: '@type'
        mapping:
          explicit: '#/components/schemas/ExplicitAccessSource'
    AppMember:
      type: object
      description: An automated app in a chat. Apps do not read messages, cannot favourite a chat and have no inbox state, so an app's row carries only the shared fields.
      required:
      - '@type'
      properties:
        '@type':
          type: string
          enum:
          - app
          example: app
        member_id:
          $ref: '#/components/schemas/MemberId'
        display_name:
          type: string
          description: The app's display name, projected from the app directory into the chat service and kept up to date via eventual consistency.
          example: Ops Bot
        access_via:
          type: array
          description: Every route by which the app has access.
          items:
            $ref: '#/components/schemas/AccessSource'
        membership:
          $ref: '#/components/schemas/Membership'
        role:
          $ref: '#/components/schemas/Role'
    InboxState:
      type: string
      description: 'Where a chat sits in one member''s own client. Private to that member: it reaches them alone and no change to it is observable by anybody else in the chat. Inbox placement is derived — a chat is in the inbox when the member has joined it and its inbox state is `active`.'
      enum:
      - active
      - archived
      - hidden
    MessageId:
      type: object
      description: Globally unique identifier for a message, composed of the owning chat id and the local message id that distinguishes the message within that chat.
      required:
      - chat_id
      - local_message_id
      properties:
        chat_id:
          type: string
          description: Globally unique identifier for a chat; a `c-` prefixed string.
          example: c-00000000-0000-0000-0000-000000000000
        local_message_id:
          type: string
          description: Identifies a message within its enclosing chat; an `m-` prefixed string. Only meaningful in combination with a chat id.
          example: m-00000000-0000-0000-0000-000000000000
    ExplicitAccessSource:
      type: object
      description: Access by a grant made on the chat.
      required:
      - '@type'
      properties:
        '@type':
          type: string
          enum:
          - explicit
          example: explicit
    SelfMember:
      type: object
      description: 'The caller''s own row: everything a user row carries, plus the state that belongs to the caller alone — their favourite flag and the inbox state deciding where the chat sits in their client.'
      required:
      - '@type'
      properties:
        '@type':
          type: string
          enum:
          - me
          example: me
        member_id:
          $ref: '#/components/schemas/MemberId'
        display_name:
          type: string
          description: The caller's display name.
          example: Alice Smith
        access_via:
          type: array
          description: Every route by which the caller has access.
          items:
            $ref: '#/components/schemas/AccessSource'
        membership:
          $ref: '#/components/schemas/Membership'
        role:
          $ref: '#/components/schemas/Role'
        read_up_to:
          $ref: '#/components/schemas/MessageId'
        favourite:
          type: boolean
          description: Whether the caller has marked the chat as a favourite; favouriting is per-member and does not affect anybody else.
          example: false
        inbox_state:
          $ref: '#/components/schemas/InboxState'
    AppPrincipal:
      type: object
      description: A principal backed by an automated app.
      required:
      - '@type'
      - app_identity_id
      properties:
        '@type':
          type: string
          enum:
          - app
          example: app
        app_identity_id:
          type: string
          description: The underlying app identity.
          example: aid-00000000-0000-0000-0000-000000000000
    UpdateMemberRole:
      type: object
      description: Parameters for updating a member's role within a chat.
      required:
      - role
      properties:
        role:
          allOf:
          - $ref: '#/components/schemas/Role'
          example: admin
    MemberId:
      type: object
      description: Globally unique identifier for a member, composed of the owning chat id and the polymorphic principal (a user or app).
      required:
      - chat_id
      - principal
      properties:
        chat_id:
          type: string
          description: Globally unique identifier for a chat; a `c-` prefixed string.
          example: c-00000000-0000-0000-0000-000000000000
        principal:
          $ref: '#/components/schemas/ChatPrincipal'
    Membership:
      type: string
      description: Whether a principal is currently in a chat. A shared fact that decides who appears in the member listing — distinct from the private inbox state, which decides only where the chat sits in one member's own client.
      enum:
      - joined
      - left
  responses:
    Forbidden:
      description: The caller is not permitted to perform this action.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    Unauthorized:
      description: Authentication is missing or invalid.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    UnprocessableEntity:
      description: The request was well-formed but failed validation.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    NotFound:
      description: The requested resource does not exist.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    BadRequest:
      description: The request body or a parameter could not be read.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
  parameters:
    UserId:
      name: userId
      in: path
      required: true
      description: Globally unique identifier for a user; a `u-` prefixed string.
      schema:
        type: string
        example: u-00000000-0000-0000-0000-000000000000
    ChatId:
      name: chatId
      in: path
      required: true
      description: Globally unique identifier for a chat; a `c-` prefixed string.
      schema:
        type: string
        example: c-00000000-0000-0000-0000-000000000000
    Cursor:
      name: cursor
      in: query
      required: false
      description: Pagination cursor token. Pass the `next_cursor` from a previous page to fetch the next one.
      schema:
        type: string
    AppIdentityId:
      name: appIdentityId
      in: path
      required: true
      description: Globally unique identifier for an app identity; an `aid-` prefixed string.
      schema:
        type: string
        example: aid-00000000-0000-0000-0000-000000000000
    Size:
      name: size
      in: query
      required: false
      description: The number of items to return per page, between 1 and 150.
      schema:
        type: integer
        format: int32
        default: 50
        minimum: 1
        maximum: 150
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A bearer token supplied in the `Authorization` header as `Authorization: Bearer <token>`.'
x-provenance:
  method: searched
  source: https://developer.joinblink.com/reference
  harvested: '2026-10-28'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developer.joinblink.com/reference/createchat.md
  - https://developer.joinblink.com/reference/deletechat.md
  - https://developer.joinblink.com/reference/deletemessage.md
  - https://developer.joinblink.com/reference/getchat.md
  - https://developer.joinblink.com/reference/getmessage.md
  - https://developer.joinblink.com/reference/getmessagepermalink.md
  - https://developer.joinblink.com/reference/getmymembership.md
  - https://developer.joinblink.com/reference/grantaccess.md
  - https://developer.joinblink.com/reference/joinchat.md
  - https://developer.joinblink.com/reference/leavechat.md
  - https://developer.joinblink.com/reference/listchatinbox.md
  - https://developer.joinblink.com/reference/listgrants.md
  - https://developer.joinblink.com/reference/listmembers.md
  - https://developer.joinblink.com/reference/listmessages.md
  - https://developer.joinblink.com/reference/removeappmember.md
  - https://developer.joinblink.com/reference/removeusermember.md
  - https://developer.joinblink.com/reference/revokeappaccess.md
  - https://developer.joinblink.com/reference/revokeuseraccess.md
  - https://developer.joinblink.com/reference/sendmessage.md
  - https://developer.joinblink.com/reference/updateappmemberrole.md
  - https://developer.joinblink.com/reference/updatechat.md
  - https://developer.joinblink.com/reference/updatemessage.md
  - https://developer.joinblink.com/reference/updateusermemberrole.md
  merge:
    pages: 23
    deduped: 380
    conflicts_kept_first: 0