Blink Access API

openapi: 3.2.0
info:
  title: Blink Chat Access 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: Access
  description: Grant and revoke access to a chat. Access is permission to be in a chat, distinct from membership of it.
paths:
  /chats/{chatId}/grants:
    get:
      tags:
      - Access
      summary: List the explicit grants made on a chat
      operationId: listGrants
      description: 'Returns a page of the grants an administrator has made, and therefore the list of things they can withdraw. A grant says only that the principal may be in the chat: to see who is actually in it, read the member listing.'
      parameters:
      - $ref: '#/components/parameters/ChatId'
      - $ref: '#/components/parameters/Size'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of grants.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorPageGrant'
        '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'
    post:
      tags:
      - Access
      summary: Grant a principal access to a chat
      operationId: grantAccess
      description: 'Grants a user or app access to the chat and returns the grant with a 201. This is how somebody is added to a chat: a grant also joins them, since being added to a chat means both.

        Granting access a grantee already holds returns the existing grant and does not rejoin them: somebody who left, or was removed while keeping their grant, comes back with `:join`.'
      parameters:
      - $ref: '#/components/parameters/ChatId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrantAccess'
            examples:
              user:
                summary: Grant a user access
                value:
                  grantee:
                    '@type': user
                    user_id: u-00000000-0000-0000-0000-000000000000
              app:
                summary: Grant an app access
                value:
                  grantee:
                    '@type': app
                    app_identity_id: aid-00000000-0000-0000-0000-000000000000
      responses:
        '201':
          description: The grant that was made (or the existing one, if already held).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Grant'
              example:
                chat_id: c-00000000-0000-0000-0000-000000000000
                grantee:
                  '@type': user
                  user_id: u-00000000-0000-0000-0000-000000000000
        '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}/grants/apps/{appIdentityId}:
    delete:
      tags:
      - Access
      summary: Revoke an app's access to a chat
      operationId: revokeAppAccess
      description: 'Withdraws an app''s grant, on the same terms as revoking a user''s: the app loses access to the chat and ceases to be a member of it.'
      parameters:
      - $ref: '#/components/parameters/ChatId'
      - $ref: '#/components/parameters/AppIdentityId'
      responses:
        '204':
          description: The grant was withdrawn. 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'
  /chats/{chatId}/grants/users/{userId}:
    delete:
      tags:
      - Access
      summary: Revoke a user's access to a chat
      operationId: revokeUserAccess
      description: Withdraws a user's grant, so they lose access to the chat and cease to be a member of it. A user with no grant on the chat answers 404. To remove somebody from the chat while leaving them able to rejoin, remove them from its members instead.
      parameters:
      - $ref: '#/components/parameters/ChatId'
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/Accept'
      responses:
        '204':
          description: The grant was withdrawn. 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:
    AppGrantee:
      type: object
      description: A single automated app, which joins the chat when granted access to it.
      required:
      - '@type'
      - app_identity_id
      properties:
        '@type':
          type: string
          enum:
          - app
          example: app
        app_identity_id:
          type: string
          description: The app granted access.
          example: aid-00000000-0000-0000-0000-000000000000
    UserGrantee:
      type: object
      description: A single user, who joins the chat when granted access to it.
      required:
      - '@type'
      - user_id
      properties:
        '@type':
          type: string
          enum:
          - user
          example: user
        user_id:
          type: string
          description: The user granted access.
          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.
    CursorPageGrant:
      type: object
      description: A page of grants.
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/Grant'
        page:
          $ref: '#/components/schemas/PageMetadata'
    GrantAccess:
      type: object
      description: Parameters for granting a user or app explicit access to a chat.
      required:
      - grantee
      properties:
        grantee:
          $ref: '#/components/schemas/Grantee'
    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.
    Grant:
      type: object
      description: 'An individual grant of access to a chat. A grant says only that the principal *may* be in the chat, not that they are: somebody who has left, or been removed by an administrator, keeps their grant.'
      properties:
        chat_id:
          type: string
          description: Globally unique identifier for a chat; a `c-` prefixed string.
          example: c-00000000-0000-0000-0000-000000000000
        grantee:
          $ref: '#/components/schemas/Grantee'
    Grantee:
      description: 'What a grant is made to: a single user or a single app. Serialised with an `@type` discriminator.'
      oneOf:
      - $ref: '#/components/schemas/UserGrantee'
      - $ref: '#/components/schemas/AppGrantee'
      discriminator:
        propertyName: '@type'
        mapping:
          user: '#/components/schemas/UserGrantee'
          app: '#/components/schemas/AppGrantee'
  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
    Accept:
      name: Accept
      in: header
      required: false
      description: The media types the client accepts.
      schema:
        type: string
        default: '*/*'
    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