Flowdock REST API

openapi: 3.0.3
info:
  title: Flowdock REST API
  version: "1.0"
  x-status: discontinued
  x-shutdown-date: "2023-08-15"
  description: |
    Historical REST API surface for CA Flowdock, a team chat and shared-inbox
    product originally built by Flowdock (Helsinki / Tampere, Finland), acquired
    by CA Technologies (2013), and later operated under Broadcom. The product
    and all hosted APIs were discontinued on August 15, 2023. Broadcom's
    sunset notice recommended Microsoft Teams or Slack as successors.

    This document is reconstructed from the public api-docs repository
    (https://github.com/flowdock/api-docs) and archived copies of
    https://www.flowdock.com/api on the Internet Archive
    (https://web.archive.org/web/20211206180655/https://www.flowdock.com/api).
    All endpoints below are now offline; this file exists for historical
    and archival purposes.
  contact:
    name: Flowdock (discontinued)
    url: https://github.com/flowdock/api-docs
  license:
    name: Documentation rights held by CA / Broadcom
servers:
  - url: https://api.flowdock.com
    description: Historical production base URL (offline since 2023-08-15)
tags:
  - name: Flows
    description: Team workspaces combining chat and a shared team inbox.
  - name: Messages
    description: Chat messages, comments, status, activity, discussion, and file events posted to a flow.
  - name: Private Conversations
    description: One-to-one direct message channels between two users.
  - name: Private Messages
    description: Messages within a private conversation.
  - name: Users
    description: User accounts that may belong to multiple organizations and flows.
  - name: Organizations
    description: Account-level container that owns flows and bills users.
  - name: Sources
    description: External integrations (GitHub, Jira, Zendesk, etc.) that post into a flow.
  - name: Invitations
    description: Open and accepted invitations to join a flow.
  - name: Files
    description: File uploads and downloads attached to messages.
  - name: Threads
    description: Threaded conversations rooted on a parent message.
  - name: Authentication
    description: OAuth 2.0 authorization-code grant for user delegation.
security:
  - oauth2: []
  - basicAuth: []
paths:
  /oauth/authorize:
    get:
      tags: [Authentication]
      summary: Begin OAuth 2.0 Authorization
      operationId: oauthAuthorize
      parameters:
        - name: client_id
          in: query
          required: true
          schema: { type: string }
        - name: response_type
          in: query
          required: true
          schema: { type: string, enum: [code] }
        - name: redirect_uri
          in: query
          schema: { type: string, format: uri }
        - name: scope
          in: query
          schema: { type: string, description: Space-delimited list of scopes (flow, private, profile). }
        - name: state
          in: query
          schema: { type: string }
      responses:
        "302":
          description: Redirect back to redirect_uri with an authorization code.
  /oauth/token:
    post:
      tags: [Authentication]
      summary: Exchange Authorization Code for Access Token
      operationId: oauthToken
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [client_id, client_secret, code, redirect_uri, grant_type]
              properties:
                client_id: { type: string }
                client_secret: { type: string }
                code: { type: string }
                redirect_uri: { type: string, format: uri }
                grant_type: { type: string, enum: [authorization_code, refresh_token] }
                refresh_token: { type: string }
      responses:
        "200":
          description: Access token issued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token: { type: string }
                  refresh_token: { type: string }
                  token_type: { type: string }
                  scope: { type: string }
  /flows:
    get:
      tags: [Flows]
      summary: List Flows For Authenticated User
      operationId: listFlows
      parameters:
        - name: users
          in: query
          description: Set to 1 to include the list of users with each flow.
          schema: { type: integer, enum: [0, 1] }
      responses:
        "200":
          description: List of joined flows.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Flow" }
  /flows/all:
    get:
      tags: [Flows]
      summary: List All Flows Visible To User
      operationId: listAllFlows
      responses:
        "200":
          description: All flows the user can see (including organization-mode flows not joined).
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Flow" }
  /flows/{organization}/{flow}:
    get:
      tags: [Flows]
      summary: Get Flow
      operationId: getFlow
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
      responses:
        "200":
          description: Flow object.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Flow" }
    put:
      tags: [Flows]
      summary: Update Flow
      operationId: updateFlow
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                open: { type: boolean }
                access_mode: { type: string, enum: [invitation, link, organization] }
      responses:
        "200": { description: Updated flow. }
  /flows/find:
    get:
      tags: [Flows]
      summary: Get Flow By Id
      operationId: getFlowById
      parameters:
        - name: id
          in: query
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Flow object.
  /flows/{organization}:
    post:
      tags: [Flows]
      summary: Create Flow
      operationId: createFlow
      parameters:
        - $ref: "#/components/parameters/Organization"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
      responses:
        "201":
          description: Flow created.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Flow" }
  /messages:
    post:
      tags: [Messages]
      summary: Send Message
      operationId: sendMessage
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/MessageInput" }
      responses:
        "201":
          description: Message accepted.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Message" }
  /flows/{organization}/{flow}/messages:
    get:
      tags: [Messages]
      summary: List Flow Messages
      operationId: listFlowMessages
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
        - name: event
          in: query
          schema: { type: string, description: Filter by event type (message, status, comment, file, activity, discussion, message-edit, tag-change). }
        - name: tags
          in: query
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer, maximum: 100 }
        - name: since_id
          in: query
          schema: { type: integer }
        - name: until_id
          in: query
          schema: { type: integer }
      responses:
        "200":
          description: List of message events.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Message" }
    post:
      tags: [Messages]
      summary: Send Message To Flow
      operationId: sendFlowMessage
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/MessageInput" }
      responses:
        "201": { description: Message accepted. }
  /flows/{organization}/{flow}/messages/{id}:
    get:
      tags: [Messages]
      summary: Show Message
      operationId: showMessage
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: Single message.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Message" }
    put:
      tags: [Messages]
      summary: Edit Message
      operationId: editMessage
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content: { type: string }
                tags:
                  type: array
                  items: { type: string }
      responses:
        "200": { description: Message updated. }
    delete:
      tags: [Messages]
      summary: Delete Message
      operationId: deleteMessage
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "204": { description: Message deleted. }
  /comments:
    post:
      tags: [Messages]
      summary: Comment On Message
      operationId: createComment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [flow, message, content]
              properties:
                flow: { type: string }
                message: { type: integer }
                content: { type: string }
                tags:
                  type: array
                  items: { type: string }
      responses:
        "201": { description: Comment posted. }
  /flows/{organization}/{flow}/threads:
    get:
      tags: [Threads]
      summary: List Flow Threads
      operationId: listFlowThreads
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
        - name: application
          in: query
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer }
      responses:
        "200":
          description: List of threads.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Thread" }
  /flows/{organization}/{flow}/threads/{id}:
    get:
      tags: [Threads]
      summary: Get Thread
      operationId: getThread
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Thread object.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Thread" }
  /flows/{organization}/{flow}/threads/{id}/messages:
    post:
      tags: [Messages]
      summary: Post Message To Thread
      operationId: postThreadMessage
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/MessageInput" }
      responses:
        "201": { description: Message posted to thread. }
  /private:
    get:
      tags: [Private Conversations]
      summary: List Private Conversations
      operationId: listPrivateConversations
      responses:
        "200":
          description: List of private conversations.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/PrivateConversation" }
  /private/{id}:
    get:
      tags: [Private Conversations]
      summary: Get Private Conversation
      operationId: getPrivateConversation
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: Private conversation.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/PrivateConversation" }
    put:
      tags: [Private Conversations]
      summary: Update Private Conversation
      operationId: updatePrivateConversation
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                open: { type: boolean }
      responses:
        "200": { description: Conversation updated. }
  /private/{id}/messages:
    get:
      tags: [Private Messages]
      summary: List Private Messages
      operationId: listPrivateMessages
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
        - name: limit
          in: query
          schema: { type: integer }
        - name: since_id
          in: query
          schema: { type: integer }
        - name: until_id
          in: query
          schema: { type: integer }
      responses:
        "200":
          description: List of private messages.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Message" }
    post:
      tags: [Private Messages]
      summary: Send Private Message
      operationId: sendPrivateMessage
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/MessageInput" }
      responses:
        "201": { description: Private message sent. }
  /private/{id}/messages/{message_id}:
    get:
      tags: [Private Messages]
      summary: Show Private Message
      operationId: showPrivateMessage
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
        - name: message_id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: Single private message.
  /users:
    get:
      tags: [Users]
      summary: List All Visible Users
      operationId: listUsers
      responses:
        "200":
          description: List of users.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/User" }
  /users/{id}:
    get:
      tags: [Users]
      summary: Get User
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: User.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/User" }
    put:
      tags: [Users]
      summary: Update User
      operationId: updateUser
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                nick: { type: string }
                email: { type: string, format: email }
      responses:
        "200": { description: User updated. }
  /flows/{organization}/{flow}/users:
    get:
      tags: [Users]
      summary: List Flow Users
      operationId: listFlowUsers
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
      responses:
        "200":
          description: List of flow users.
    post:
      tags: [Users]
      summary: Add User To Flow
      operationId: addUserToFlow
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: integer }
      responses:
        "200": { description: User added to flow. }
  /flows/{organization}/{flow}/users/{id}:
    delete:
      tags: [Users]
      summary: Remove User From Flow
      operationId: removeUserFromFlow
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "204": { description: User removed. }
  /organizations:
    get:
      tags: [Organizations]
      summary: List Organizations
      operationId: listOrganizations
      responses:
        "200":
          description: List of organizations.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Organization" }
  /organizations/{parameterized_name}:
    get:
      tags: [Organizations]
      summary: Get Organization
      operationId: getOrganization
      parameters:
        - name: parameterized_name
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Organization.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Organization" }
    put:
      tags: [Organizations]
      summary: Update Organization
      operationId: updateOrganization
      parameters:
        - name: parameterized_name
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                parameterized_name: { type: string }
      responses:
        "200": { description: Organization updated. }
  /organizations/{organization}/users/{id}:
    delete:
      tags: [Users]
      summary: Remove User From Organization
      operationId: removeUserFromOrganization
      parameters:
        - $ref: "#/components/parameters/Organization"
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "204": { description: User removed. }
  /sources:
    get:
      tags: [Sources]
      summary: List Sources
      operationId: listSources
      responses:
        "200":
          description: List of sources visible to the user.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Source" }
  /flows/{organization}/{flow}/sources:
    get:
      tags: [Sources]
      summary: List Flow Sources
      operationId: listFlowSources
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
      responses:
        "200":
          description: List of sources attached to the flow.
    post:
      tags: [Sources]
      summary: Create Source
      operationId: createSource
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
                external_url: { type: string, format: uri }
      responses:
        "201":
          description: Source created.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Source" }
  /flows/{organization}/{flow}/sources/{id}:
    get:
      tags: [Sources]
      summary: Get Source
      operationId: getSource
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200": { description: Source. }
    put:
      tags: [Sources]
      summary: Update Source
      operationId: updateSource
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                external_url: { type: string, format: uri }
      responses:
        "200": { description: Source updated. }
    delete:
      tags: [Sources]
      summary: Delete Source
      operationId: deleteSource
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "204": { description: Source deleted. }
  /flows/{organization}/{flow}/invitations:
    get:
      tags: [Invitations]
      summary: List Flow Invitations
      operationId: listInvitations
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
      responses:
        "200":
          description: List of pending and accepted invitations.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Invitation" }
    post:
      tags: [Invitations]
      summary: Create Invitation
      operationId: createInvitation
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email: { type: string, format: email }
                message: { type: string }
      responses:
        "201":
          description: Invitation created.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Invitation" }
  /flows/{organization}/{flow}/invitations/{id}:
    get:
      tags: [Invitations]
      summary: Get Invitation
      operationId: getInvitation
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: Invitation.
    delete:
      tags: [Invitations]
      summary: Delete Invitation
      operationId: deleteInvitation
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "204": { description: Invitation revoked. }
  /flows/{organization}/{flow}/invitations/import:
    post:
      tags: [Invitations]
      summary: Import Address List
      operationId: importInvitations
      parameters:
        - $ref: "#/components/parameters/Organization"
        - $ref: "#/components/parameters/FlowName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [addresses]
              properties:
                addresses:
                  type: array
                  items: { type: string, format: email }
                message: { type: string }
      responses:
        "200": { description: Addresses imported. }
  /files/{organization}/{hash}/{filename}:
    get:
      tags: [Files]
      summary: Download File
      operationId: downloadFile
      parameters:
        - name: organization
          in: path
          required: true
          schema: { type: integer, description: Numeric organization id used in file paths. }
        - name: hash
          in: path
          required: true
          schema: { type: string }
        - name: filename
          in: path
          required: true
          schema: { type: string }
      responses:
        "302":
          description: Redirect to a short-lived S3 download URL.
          headers:
            Location:
              schema: { type: string, format: uri }
components:
  parameters:
    Organization:
      name: organization
      in: path
      required: true
      description: Organization parameterized name.
      schema: { type: string }
    FlowName:
      name: flow
      in: path
      required: true
      description: Flow parameterized name within the organization.
      schema: { type: string }
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.flowdock.com/oauth/authorize
          tokenUrl: https://api.flowdock.com/oauth/token
          scopes:
            flow: Read and write flow content.
            private: Read and write private conversations.
            profile: Read user profile.
    basicAuth:
      type: http
      scheme: basic
      description: Email + password, or personal API token as the username.
  schemas:
    Flow:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        parameterized_name: { type: string }
        organization: { $ref: "#/components/schemas/Organization" }
        unread_mentions: { type: integer }
        open: { type: boolean }
        joined: { type: boolean }
        url: { type: string, format: uri }
        web_url: { type: string, format: uri }
        join_url: { type: string, format: uri }
        access_mode:
          type: string
          enum: [invitation, link, organization]
    MessageInput:
      type: object
      required: [event, content]
      properties:
        event:
          type: string
          enum: [message, status, comment, action, activity, discussion, file]
        content:
          oneOf:
            - type: string
            - type: object
        flow: { type: string }
        message: { type: integer }
        tags:
          type: array
          items: { type: string }
        external_user_name: { type: string }
        uuid: { type: string }
        thread_id: { type: string }
        external_thread_id: { type: string }
    Message:
      type: object
      properties:
        id: { type: integer }
        app: { type: string }
        event: { type: string }
        flow: { type: string }
        content: {}
        sent: { type: integer, format: int64 }
        user: { type: string }
        created_at: { type: string, format: date-time }
        tags:
          type: array
          items: { type: string }
        attachments:
          type: array
          items: { type: object }
        thread_id: { type: string }
        thread: { $ref: "#/components/schemas/Thread" }
        uuid: { type: string }
    Thread:
      type: object
      properties:
        id: { type: string }
        title: { type: string }
        body: { type: string }
        status:
          type: object
          properties:
            color: { type: string }
            value: { type: string }
        fields:
          type: array
          items:
            type: object
            properties:
              label: { type: string }
              value: { type: string }
        actions:
          type: array
          items: { type: object }
        external_url: { type: string, format: uri }
        actor:
          type: object
          properties:
            name: { type: string }
            avatar: { type: string, format: uri }
    User:
      type: object
      properties:
        id: { type: integer }
        email: { type: string, format: email }
        name: { type: string }
        nick: { type: string }
        avatar: { type: string, format: uri }
        website: { type: string, format: uri }
        admin: { type: boolean }
    Organization:
      type: object
      properties:
        id: { type: integer }
        parameterized_name: { type: string }
        name: { type: string }
        user_limit: { type: integer }
        user_count: { type: integer }
        active: { type: boolean }
        url: { type: string, format: uri }
        subscription:
          type: object
          properties:
            trial: { type: boolean }
            trial_ends: { type: string, format: date }
            billing_date: { type: string, format: date }
    Source:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        url: { type: string, format: uri }
        external_url: { type: string, format: uri }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        application:
          type: object
          properties:
            id: { type: integer }
            name: { type: string }
            icon_url: { type: string, format: uri }
            url: { type: string, format: uri }
        creator: { $ref: "#/components/schemas/User" }
    Invitation:
      type: object
      properties:
        id: { type: integer }
        state: { type: string, enum: [pending, accepted] }
        email: { type: string, format: email }
        flow: { type: string }
        url: { type: string, format: uri }
    PrivateConversation:
      type: object
      properties:
        id: { type: integer }
        url: { type: string, format: uri }
        name: { type: string }
        open: { type: boolean }
        activity:
          type: object
          properties:
            inbox: { type: boolean }
            mentions: { type: integer }
            chat: { type: boolean }
        users:
          type: array
          items: { $ref: "#/components/schemas/User" }