chatrail-dev Team API

openapi: 3.2.0
info:
  title: ChatRail Team API
  version: 1.0.0
  description: 'Send, schedule and receive WhatsApp messages through a linked-device session.


    **Two things the API is careful about, which shape every endpoint below.**


    *Accepted is not delivered.* A 202 means the message is durably stored and queued. Only the `status` field ever claims WhatsApp delivered anything, and `queued`, `submitted`, `sent`, `delivered` and `read` are deliberately distinct.


    *A retry must not send twice.* Send `Idempotency-Key` on every send. A replay returns the original response; a concurrent duplicate is told to retry rather than allowed to race.'
  contact:
    name: ChatRail
    url: https://www.chatrail.dev
servers:
- url: https://www.chatrail.dev
security:
- apiKey: []
tags:
- name: Team
  description: Membership and invitations. Dashboard sessions only.
paths:
  /v1/members:
    get:
      summary: List members and pending invitations
      tags:
      - Team
      operationId: get_v1_members
      responses:
        '200':
          description: Members, invitations, and the roles this caller may assign.
      security:
      - session: []
  /v1/members/invitations:
    post:
      summary: Invite somebody
      description: Emails a single-use link bound to that address. The token is never returned in the response. Nobody may invite to a role above their own.
      tags:
      - Team
      operationId: post_v1_members_invitations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  maxLength: 254
                  format: email
                  pattern: ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                role:
                  type: string
                  enum:
                  - owner
                  - admin
                  - developer
                  - viewer
                  - billing
              required:
              - email
              - role
              additionalProperties: false
            example:
              email: colleague@company.com
              role: viewer
      responses:
        '201':
          description: Invited.
        '402':
          description: Member management is not on this plan.
        '403':
          description: You cannot assign that role.
        '409':
          description: Already a member.
      security:
      - session: []
  /v1/members/invitations/{id}:
    delete:
      summary: Revoke an invitation
      tags:
      - Team
      operationId: delete_v1_members_invitations__id_
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Invitation id.
      responses:
        '204':
          description: Revoked.
        '404':
          description: No such invitation.
      security:
      - session: []
  /v1/members/invitations/{id}/resend:
    post:
      summary: Resend an invitation
      description: Emails the invitation again with a fresh link. Dashboard only.
      tags:
      - Team
      operationId: post_v1_members_invitations__id__resend
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Invitation id.
      responses:
        '200':
          description: Resent.
        '404':
          description: No such invitation.
      security:
      - session: []
  /v1/members/accept:
    post:
      summary: Accept an invitation
      description: Requires a signed-in session whose address matches the invited one. Possessing the token is not enough — a forwarded invitation email must not be a way into a workspace.
      tags:
      - Team
      operationId: post_v1_members_accept
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                  minLength: 20
                  maxLength: 200
              required:
              - token
              additionalProperties: false
            example:
              token: the token from the invitation link
      responses:
        '200':
          description: Joined.
        '401':
          description: Sign in as the invited address first.
        '403':
          description: The invitation was sent to a different address.
        '404':
          description: The invitation is not valid.
      security:
      - session: []
  /v1/members/{id}:
    patch:
      summary: Change a member's role
      tags:
      - Team
      operationId: patch_v1_members__id_
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: User id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  type: string
                  enum:
                  - owner
                  - admin
                  - developer
                  - viewer
                  - billing
              required:
              - role
              additionalProperties: false
            example:
              role: developer
      responses:
        '200':
          description: The updated member.
        '403':
          description: You cannot assign or act on that role.
        '409':
          description: A workspace must keep an owner.
      security:
      - session: []
    delete:
      summary: Remove a member
      tags:
      - Team
      operationId: delete_v1_members__id_
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: User id.
      responses:
        '204':
          description: Removed.
        '409':
          description: A workspace must keep an owner.
      security:
      - session: []
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'A workspace API key, `cr_live_…`. Server-side only: it carries workspace authority and must never reach a browser.'
    session:
      type: apiKey
      in: cookie
      name: chatrail_session
      description: Dashboard session cookie. Set by `/v1/auth/verify`.