Chatwork API v2

openapi: 3.1.0
info:
  title: Chatwork API v2
  version: "2"
  description: |
    REST API for Chatwork business messaging. Authentication uses an API
    token sent in the X-ChatWorkToken HTTP header, or OAuth 2.0 for third-
    party integrations. Endpoint inventory sourced from the official
    developer documentation index at https://developer.chatwork.com/llms.txt.
  contact:
    name: Chatwork Developer Portal
    url: https://developer.chatwork.com
servers:
  - url: https://api.chatwork.com/v2
security:
  - chatworkToken: []
tags:
  - name: Me
  - name: Contacts
  - name: Incoming Requests
  - name: Rooms
  - name: Messages
  - name: Members
  - name: Files
  - name: Tasks
  - name: Link
paths:
  /me:
    get:
      tags: [Me]
      summary: Retrieve your account information
      operationId: getMe
      responses:
        "200":
          description: Account info
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Me" }
  /my/status:
    get:
      tags: [Me]
      summary: Retrieve your unread, mentions, and task counts
      operationId: getMyStatus
      responses:
        "200":
          description: Status counts
          content:
            application/json:
              schema: { $ref: "#/components/schemas/MyStatus" }
  /my/tasks:
    get:
      tags: [Me]
      summary: Retrieve your tasks across all rooms
      operationId: getMyTasks
      parameters:
        - { in: query, name: assigned_by_account_id, schema: { type: integer } }
        - { in: query, name: status, schema: { type: string, enum: [open, done] } }
      responses:
        "200":
          description: Task list
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Task" }
  /contacts:
    get:
      tags: [Contacts]
      summary: List your contacts
      operationId: listContacts
      responses:
        "200":
          description: Contacts
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Contact" }
  /incoming_requests:
    get:
      tags: [Incoming Requests]
      summary: List incoming contact requests
      operationId: listIncomingRequests
      responses:
        "200":
          description: Requests
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/IncomingRequest" }
  /incoming_requests/{request_id}:
    parameters:
      - { in: path, name: request_id, required: true, schema: { type: integer } }
    put:
      tags: [Incoming Requests]
      summary: Approve an incoming contact request
      operationId: approveIncomingRequest
      responses:
        "200":
          description: Approved
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Contact" }
    delete:
      tags: [Incoming Requests]
      summary: Reject an incoming contact request
      operationId: rejectIncomingRequest
      responses:
        "204": { description: Rejected }
  /rooms:
    get:
      tags: [Rooms]
      summary: List rooms you belong to
      operationId: listRooms
      responses:
        "200":
          description: Rooms
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Room" }
    post:
      tags: [Rooms]
      summary: Create a new group chat room
      operationId: createRoom
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema: { $ref: "#/components/schemas/RoomCreate" }
      responses:
        "200":
          description: Created
          content:
            application/json:
              schema: { type: object, properties: { room_id: { type: integer } } }
  /rooms/{room_id}:
    parameters:
      - { in: path, name: room_id, required: true, schema: { type: integer } }
    get:
      tags: [Rooms]
      summary: Retrieve a room
      operationId: getRoom
      responses:
        "200":
          description: Room
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Room" }
    put:
      tags: [Rooms]
      summary: Update a room
      operationId: updateRoom
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema: { $ref: "#/components/schemas/RoomUpdate" }
      responses:
        "200":
          description: Updated
          content:
            application/json:
              schema: { type: object }
    delete:
      tags: [Rooms]
      summary: Leave or delete a room
      operationId: deleteRoom
      parameters:
        - { in: query, name: action_type, required: true, schema: { type: string, enum: [leave, delete] } }
      responses:
        "204": { description: Done }
  /rooms/{room_id}/members:
    parameters:
      - { in: path, name: room_id, required: true, schema: { type: integer } }
    get:
      tags: [Members]
      summary: List room members
      operationId: listRoomMembers
      responses:
        "200":
          description: Members
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Member" }
    put:
      tags: [Members]
      summary: Update room members and their roles
      operationId: updateRoomMembers
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                members_admin_ids: { type: string }
                members_member_ids: { type: string }
                members_readonly_ids: { type: string }
      responses:
        "200":
          description: Updated
          content:
            application/json:
              schema: { type: object }
  /rooms/{room_id}/messages:
    parameters:
      - { in: path, name: room_id, required: true, schema: { type: integer } }
    get:
      tags: [Messages]
      summary: List messages in a room
      operationId: listRoomMessages
      parameters:
        - { in: query, name: force, schema: { type: integer, enum: [0, 1] } }
      responses:
        "200":
          description: Messages
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Message" }
    post:
      tags: [Messages]
      summary: Post a new message in a room
      operationId: postRoomMessage
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [body]
              properties:
                body: { type: string }
                self_unread: { type: integer, enum: [0, 1] }
      responses:
        "200":
          description: Posted
          content:
            application/json:
              schema: { type: object, properties: { message_id: { type: string } } }
  /rooms/{room_id}/messages/read:
    parameters:
      - { in: path, name: room_id, required: true, schema: { type: integer } }
    put:
      tags: [Messages]
      summary: Mark messages in a room as read
      operationId: markRoomRead
      responses:
        "200":
          description: Read marker
          content:
            application/json:
              schema: { type: object }
  /rooms/{room_id}/messages/unread:
    parameters:
      - { in: path, name: room_id, required: true, schema: { type: integer } }
    put:
      tags: [Messages]
      summary: Mark messages in a room as unread from a message
      operationId: markRoomUnread
      responses:
        "200":
          description: Unread marker
          content:
            application/json:
              schema: { type: object }
  /rooms/{room_id}/messages/{message_id}:
    parameters:
      - { in: path, name: room_id, required: true, schema: { type: integer } }
      - { in: path, name: message_id, required: true, schema: { type: string } }
    get:
      tags: [Messages]
      summary: Retrieve a message
      operationId: getMessage
      responses:
        "200":
          description: Message
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Message" }
    put:
      tags: [Messages]
      summary: Update a message
      operationId: updateMessage
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [body]
              properties:
                body: { type: string }
      responses:
        "200":
          description: Updated
          content:
            application/json:
              schema: { type: object }
    delete:
      tags: [Messages]
      summary: Delete a message
      operationId: deleteMessage
      responses:
        "200":
          description: Deleted
          content:
            application/json:
              schema: { type: object }
  /rooms/{room_id}/tasks:
    parameters:
      - { in: path, name: room_id, required: true, schema: { type: integer } }
    get:
      tags: [Tasks]
      summary: List tasks in a room
      operationId: listRoomTasks
      responses:
        "200":
          description: Tasks
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Task" }
    post:
      tags: [Tasks]
      summary: Create a task in a room
      operationId: createRoomTask
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [body, to_ids]
              properties:
                body: { type: string }
                to_ids: { type: string, description: "Comma-separated account IDs to assign" }
                limit: { type: integer }
                limit_type: { type: string, enum: [none, date, time] }
      responses:
        "200":
          description: Created
          content:
            application/json:
              schema: { type: object, properties: { task_ids: { type: array, items: { type: integer } } } }
  /rooms/{room_id}/tasks/{task_id}:
    parameters:
      - { in: path, name: room_id, required: true, schema: { type: integer } }
      - { in: path, name: task_id, required: true, schema: { type: integer } }
    get:
      tags: [Tasks]
      summary: Retrieve a task
      operationId: getRoomTask
      responses:
        "200":
          description: Task
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Task" }
  /rooms/{room_id}/tasks/{task_id}/status:
    parameters:
      - { in: path, name: room_id, required: true, schema: { type: integer } }
      - { in: path, name: task_id, required: true, schema: { type: integer } }
    put:
      tags: [Tasks]
      summary: Update the status of a task
      operationId: updateRoomTaskStatus
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [body]
              properties:
                body: { type: string, enum: [done, open] }
      responses:
        "200":
          description: Updated
          content:
            application/json:
              schema: { type: object }
  /rooms/{room_id}/files:
    parameters:
      - { in: path, name: room_id, required: true, schema: { type: integer } }
    get:
      tags: [Files]
      summary: List files in a room
      operationId: listRoomFiles
      parameters:
        - { in: query, name: account_id, schema: { type: integer } }
      responses:
        "200":
          description: Files
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/File" }
    post:
      tags: [Files]
      summary: Upload a file to a room
      operationId: uploadRoomFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: { type: string, format: binary }
                message: { type: string }
      responses:
        "200":
          description: Uploaded
          content:
            application/json:
              schema: { type: object, properties: { file_id: { type: integer } } }
  /rooms/{room_id}/files/{file_id}:
    parameters:
      - { in: path, name: room_id, required: true, schema: { type: integer } }
      - { in: path, name: file_id, required: true, schema: { type: integer } }
    get:
      tags: [Files]
      summary: Retrieve file metadata or download URL
      operationId: getRoomFile
      parameters:
        - { in: query, name: create_download_url, schema: { type: integer, enum: [0, 1] } }
      responses:
        "200":
          description: File metadata
          content:
            application/json:
              schema: { $ref: "#/components/schemas/File" }
  /rooms/{room_id}/link:
    parameters:
      - { in: path, name: room_id, required: true, schema: { type: integer } }
    get:
      tags: [Link]
      summary: Retrieve invitation link
      operationId: getRoomLink
      responses:
        "200":
          description: Link
          content:
            application/json:
              schema: { $ref: "#/components/schemas/InviteLink" }
    post:
      tags: [Link]
      summary: Create invitation link
      operationId: createRoomLink
      responses:
        "200":
          description: Created
          content:
            application/json:
              schema: { $ref: "#/components/schemas/InviteLink" }
    put:
      tags: [Link]
      summary: Update invitation link
      operationId: updateRoomLink
      responses:
        "200":
          description: Updated
          content:
            application/json:
              schema: { $ref: "#/components/schemas/InviteLink" }
    delete:
      tags: [Link]
      summary: Delete invitation link
      operationId: deleteRoomLink
      responses:
        "204": { description: Deleted }
components:
  securitySchemes:
    chatworkToken:
      type: apiKey
      in: header
      name: X-ChatWorkToken
      description: API token issued from your Chatwork account settings.
  schemas:
    Me:
      type: object
      properties:
        account_id: { type: integer }
        room_id: { type: integer }
        name: { type: string }
        chatwork_id: { type: string }
        organization_id: { type: integer }
        organization_name: { type: string }
        department: { type: string }
        title: { type: string }
        avatar_image_url: { type: string, format: uri }
    MyStatus:
      type: object
      properties:
        unread_room_num: { type: integer }
        mention_room_num: { type: integer }
        mytask_room_num: { type: integer }
        unread_num: { type: integer }
        mention_num: { type: integer }
        mytask_num: { type: integer }
    Contact:
      type: object
      properties:
        account_id: { type: integer }
        room_id: { type: integer }
        name: { type: string }
        chatwork_id: { type: string }
        avatar_image_url: { type: string, format: uri }
    IncomingRequest:
      type: object
      properties:
        request_id: { type: integer }
        account_id: { type: integer }
        message: { type: string }
        name: { type: string }
    Room:
      type: object
      properties:
        room_id: { type: integer }
        name: { type: string }
        type: { type: string, enum: [my, direct, group] }
        role: { type: string, enum: [admin, member, readonly] }
        sticky: { type: boolean }
        unread_num: { type: integer }
        mention_num: { type: integer }
        mytask_num: { type: integer }
        message_num: { type: integer }
        file_num: { type: integer }
        task_num: { type: integer }
        icon_path: { type: string, format: uri }
        description: { type: string }
    RoomCreate:
      type: object
      required: [name, members_admin_ids]
      properties:
        name: { type: string }
        description: { type: string }
        link: { type: integer, enum: [0, 1] }
        link_code: { type: string }
        link_need_acceptance: { type: integer, enum: [0, 1] }
        members_admin_ids: { type: string }
        members_member_ids: { type: string }
        members_readonly_ids: { type: string }
        icon_preset: { type: string }
    RoomUpdate:
      type: object
      properties:
        name: { type: string }
        description: { type: string }
        icon_preset: { type: string }
    Member:
      type: object
      properties:
        account_id: { type: integer }
        role: { type: string, enum: [admin, member, readonly] }
        name: { type: string }
        chatwork_id: { type: string }
        avatar_image_url: { type: string, format: uri }
    Message:
      type: object
      properties:
        message_id: { type: string }
        account:
          type: object
          properties:
            account_id: { type: integer }
            name: { type: string }
            avatar_image_url: { type: string, format: uri }
        body: { type: string }
        send_time: { type: integer, format: int64 }
        update_time: { type: integer, format: int64 }
    Task:
      type: object
      properties:
        task_id: { type: integer }
        room:
          type: object
          properties:
            room_id: { type: integer }
            name: { type: string }
            icon_path: { type: string, format: uri }
        assigned_by_account:
          type: object
          properties:
            account_id: { type: integer }
            name: { type: string }
            avatar_image_url: { type: string, format: uri }
        message_id: { type: string }
        body: { type: string }
        limit_time: { type: integer, format: int64 }
        status: { type: string, enum: [open, done] }
        limit_type: { type: string, enum: [none, date, time] }
    File:
      type: object
      properties:
        file_id: { type: integer }
        account:
          type: object
          properties:
            account_id: { type: integer }
            name: { type: string }
            avatar_image_url: { type: string, format: uri }
        message_id: { type: string }
        filename: { type: string }
        filesize: { type: integer }
        upload_time: { type: integer, format: int64 }
        download_url: { type: string, format: uri }
    InviteLink:
      type: object
      properties:
        public: { type: boolean }
        url: { type: string, format: uri }
        need_acceptance: { type: boolean }
        description: { type: string }