Blink Chats API

openapi: 3.2.0
info:
  title: Blink Chat Chats 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: Chats
  description: Create, read, update and delete chats.
paths:
  /chats:
    post:
      tags:
      - Chats
      summary: Create a new chat
      operationId: createChat
      description: 'Creates a new chat and returns it in full, exactly as a subsequent GET of the chat would.

        `members` states who is in the chat from creation: each named principal is joined outright, on an explicit grant recorded alongside. Nobody else is put in the chat, the creator included, so name the calling app here if it is to take part. At least one member is required.

        Private chats created without a title are unique per set of members: creating another untitled chat with the same members returns the existing chat rather than creating a duplicate. When a title is supplied a new chat is always created. The creator, attributed on the chat''s automatically generated header message, is always the caller''s authenticated identity and never anything in the request body.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChat'
            examples:
              private:
                summary: Private chat between an app and a user
                value:
                  organisation_id: o-00000000-0000-0000-0000-000000000000
                  title: Shift, 10-14 Aug
                  access_rule:
                    '@type': private
                  members:
                  - '@type': app
                    app_identity_id: aid-00000000-0000-0000-0000-000000000000
                  - '@type': user
                    user_id: u-00000000-0000-0000-0000-000000000000
                  description: Conversation linked to our shifts
                  icon: a-00000000-0000-0000-0000-000000000000
      responses:
        '201':
          description: The chat was created (or the existing untitled chat was returned).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chat'
        '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/inbox:
    get:
      tags:
      - Chats
      summary: List the caller's inbox
      operationId: listChatInbox
      description: 'Returns a page of inbox entries — each pairing a chat with a preview of its most recent message — most-recent-activity first. There is no parameter for whose inbox to read: it is always the caller''s. An app holds no inbox state, so every chat it has joined is in its inbox; a chat it has left is not.'
      parameters:
      - $ref: '#/components/parameters/Size'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of inbox entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorPageChatInboxEntry'
        '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}:
    get:
      tags:
      - Chats
      summary: Look up a single chat
      operationId: getChat
      description: Looks up a single chat by its identifier and returns it in full.
      parameters:
      - $ref: '#/components/parameters/ChatId'
      responses:
        '200':
          description: The chat.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chat'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    patch:
      tags:
      - Chats
      summary: Update a chat's metadata
      operationId: updateChat
      description: 'Updates the mutable metadata (title, description, icon) of an existing chat, and returns the updated chat in full. Description and icon follow three-state PATCH semantics: omit a field to leave it unchanged, send `null` to clear it, or send a value to set it. The title cannot be cleared.'
      parameters:
      - $ref: '#/components/parameters/ChatId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateChat'
      responses:
        '200':
          description: The updated chat.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chat'
        '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:
      - Chats
      summary: Delete a chat
      operationId: deleteChat
      description: Deletes a chat along with its members, grants and messages. After deletion the chat can no longer be looked up and will not be returned from any inbox query. For untitled chats the membership-based dedupe entry is also cleared, so a subsequent create call with the same members will produce a fresh chat.
      parameters:
      - $ref: '#/components/parameters/ChatId'
      responses:
        '204':
          description: The chat was deleted. The response body is empty.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    App:
      type: object
      description: A message sent by an automated app.
      required:
      - '@type'
      properties:
        '@type':
          type: string
          enum:
          - app
          example: app
        app_identity_id:
          type: string
          description: The app that sent the message.
          example: aid-00000000-0000-0000-0000-000000000000
    Private:
      type: object
      description: Gives access only to those individually granted. All access to the chat is by a grant, listed in the chat's grants collection; granting one also joins the principal.
      required:
      - '@type'
      properties:
        '@type':
          type: string
          enum:
          - private
          example: private
    CursorPageChatInboxEntry:
      type: object
      description: A page of chat inbox entries.
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/ChatInboxEntry'
        page:
          $ref: '#/components/schemas/PageMetadata'
    Sender:
      description: The originator of a message. A message read back may have been sent by a user, by a user acting under an alias, by an app, or by the system itself (for membership changes, chat lifecycle events, etc.). Serialised with an `@type` discriminator. When sending a message only the authenticated app may be named as the sender — see `SendMessage`.
      oneOf:
      - $ref: '#/components/schemas/User'
      - $ref: '#/components/schemas/Alias'
      - $ref: '#/components/schemas/App'
      - $ref: '#/components/schemas/System'
      discriminator:
        propertyName: '@type'
        mapping:
          user: '#/components/schemas/User'
          alias: '#/components/schemas/Alias'
          app: '#/components/schemas/App'
          system: '#/components/schemas/System'
    CreateChat:
      type: object
      description: 'Parameters for creating a new chat. `members` states who is in the chat from creation: each named principal is joined outright, on a grant recorded alongside. Nobody else is put in the chat, the creator included, so name the calling app here if it is to take part. At least one member is required.'
      required:
      - organisation_id
      - access_rule
      - members
      properties:
        organisation_id:
          type: string
          description: The organisation that owns the chat.
          example: o-00000000-0000-0000-0000-000000000000
        title:
          type: string
          description: Optional display title for the chat; whitespace alone is not a title. An untitled chat is unique per set of members.
          example: Project Phoenix
        access_rule:
          $ref: '#/components/schemas/AccessRule'
        members:
          type: array
          description: The principals who are in the chat from creation; nobody else is put in the chat, the creator included. At least one is required.
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ChatPrincipal'
        description:
          type: string
          description: Optional longer description.
          example: Coordination for the Phoenix rollout
        icon:
          type: string
          description: Optional icon for the chat, given as the id of an existing attachment.
          example: a-00000000-0000-0000-0000-000000000000
    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'
    ChatInboxEntry:
      type: object
      description: 'An entry in a chat inbox: the chat plus a preview of its most recent message, if any.'
      properties:
        chat:
          $ref: '#/components/schemas/Chat'
        latest_message:
          $ref: '#/components/schemas/MessagePreview'
    Chat:
      type: object
      description: 'A Blink chat: a thread of communication between the users and apps granted access to it.'
      properties:
        chat_id:
          type: string
          description: Globally unique identifier for a chat; a `c-` prefixed string.
          example: c-00000000-0000-0000-0000-000000000000
        organisation_id:
          type: string
          description: The organisation that owns this chat.
          example: o-00000000-0000-0000-0000-000000000000
        access_rule:
          $ref: '#/components/schemas/AccessRule'
        members:
          $ref: '#/components/schemas/MembersPreview'
        title:
          type: string
          description: Optional human-readable title.
          example: Project Phoenix
        description:
          type: string
          description: Optional longer description.
          example: Coordination for the Phoenix rollout
        icon:
          type: string
          description: Optional icon for the chat, given as the id of an existing attachment.
          example: a-00000000-0000-0000-0000-000000000000
    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
    Alias:
      type: object
      description: A message sent by a user posting under an alias.
      required:
      - '@type'
      properties:
        '@type':
          type: string
          enum:
          - alias
          example: alias
        user_id:
          type: string
          description: The underlying user who sent the message.
          example: u-00000000-0000-0000-0000-000000000000
        alias_id:
          type: string
          description: The alias the user was posting as.
          example: al-00000000-0000-0000-0000-000000000000
    User:
      type: object
      description: A message sent by a regular user, posting under their own identity.
      required:
      - '@type'
      properties:
        '@type':
          type: string
          enum:
          - user
          example: user
        user_id:
          type: string
          description: The user who sent the message.
          example: u-00000000-0000-0000-0000-000000000000
    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.
    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.
    System:
      type: object
      description: A message generated by the chat system itself, rather than by any user or app. Used for system notices such as membership changes or chat lifecycle events.
      required:
      - '@type'
      properties:
        '@type':
          type: string
          enum:
          - system
          example: system
    MembersPreview:
      type: object
      description: A bounded sample of a chat's members, so that a listing can name an untitled chat without a call per row. Carries principal identifiers alone, ordered by id and capped at ten; the members listing remains the full answer.
      properties:
        preview:
          type: array
          description: Up to ten of the chat's members, ordered by principal id.
          items:
            $ref: '#/components/schemas/ChatPrincipal'
    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
    UpdateChat:
      type: object
      description: 'Parameters for updating an existing chat''s metadata. The description and icon follow three-state PATCH semantics: omit a field to leave it unchanged, send `null` to clear it, or send a value to set it. The title cannot be cleared.'
      properties:
        title:
          type: string
          description: New title, if it should be changed; cannot be cleared.
          example: Phoenix — Phase 2
        description:
          type:
          - string
          - 'null'
          description: 'Three-state update for the description: omit to leave unchanged, `null` to clear, value to set.'
          example: Coordination for the Phoenix Phase 2 rollout
        icon:
          type:
          - string
          - 'null'
          description: 'Three-state update for the icon, given as the id of an existing attachment: omit to leave unchanged, `null` to clear, value to set.'
          example: a-00000000-0000-0000-0000-000000000000
    AccessRule:
      description: 'States who *may* be in a chat — not who is. A rule names the predicate that governs the chat and carries nothing of its own: who is in the chat from creation travels beside it, on the create command''s `members`, and access given afterwards lives in the chat''s grants collection. Serialised with an `@type` discriminator.'
      oneOf:
      - $ref: '#/components/schemas/Private'
      discriminator:
        propertyName: '@type'
        mapping:
          private: '#/components/schemas/Private'
    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
    MessagePreview:
      type: object
      description: A compact view of a message suitable for inbox listings and notifications.
      properties:
        message_id:
          $ref: '#/components/schemas/MessageId'
        sender:
          $ref: '#/components/schemas/Sender'
        created_at:
          type: string
          format: date-time
          description: The instant the message was originally sent.
          example: '2026-05-14T09:30:00Z'
        text:
          type: string
          description: Textual rendering of the message, suitable for previews and notifications.
          example: Hello, world!
  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:
    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
    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