Go to section …

Sources

Sources provide content from external sources to a flow. These include integrations such as GitHub, Rally and Zendesk. Each source has a secret flow_token that is used for authentication when posting content to a flow.

Sources can be accessed with flow token authentication, in which case only the specific source is exposed. Creating new sources requires OAuth 2.0 authorization by an end user. See the exhaustive integration guide for more information on building integrations that use the OAuth framework.

If you just want to post messages to your own flows, have a look at the the quick integration guide for instructions on how to create sources without the OAuth authorization process.

List Sources

Lists all sources visible for user.

GET /sources

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Flowdock-User: 2

[
  {
    "id": 1,
    "name": "Example",
    "url": "https://api.flowdock.com/flows/example/main/sources/1",
    "created_at": "2014-10-14T11:05:27.176Z",
    "updated_at": "2014-10-14T11:05:27.176Z",
    "_links": {},
    "application": {
      "id": 327,
      "name": "Zendesk",
      "icon_url": "https://dxgv4vuja9avs.cloudfront.net/applications/327/64981f9198413209.png",
      "url": "http://api.flowdock.com/oauth/applications/327"
    },
    "creator": {
      "id": 1,
      "avatar": "https://d2cxspbh1aoie1.cloudfront.net/avatars/f0b4520a6e0001636bf8fc1431af151c",
      "email": "testuser@example.com",
      "name": "User",
      "nick": "User",
      "website": "http://www.example.com/"
    }
  },
  {
    "id": 2,
    "name": "Engineering",
    "url": "https://api.flowdock.com/flows/example/other/sources/2",
    "external_url": "https://acme.example.com/polls/helsinki",
    "created_at": "2014-10-14T11:05:27.007Z",
    "updated_at": "2014-10-14T11:05:27.007Z",
    "_links": {},
    "application": {
      "id": 327,
      "name": "Zendesk",
      "icon_url": "https://dxgv4vuja9avs.cloudfront.net/applications/327/64981f9198413209.png",
      "url": "http://api.flowdock.com/oauth/applications/327"
    },
    "creator": {
      "id": 1,
      "avatar": "https://d2cxspbh1aoie1.cloudfront.net/avatars/f0b4520a6e0001636bf8fc1431af151c",
      "email": "testuser@example.com",
      "name": "User",
      "nick": "User",
      "website": "http://www.example.com/"
    }
  }
]

List Flow Sources

Lists all the sources of the given flow.

GET /flows/:organization/:flow/sources

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Flowdock-User: 2

[
  {
    "id": 1,
    "name": "Example",
    "url": "https://api.flowdock.com/flows/example/main/sources/1",
    "created_at": "2014-10-14T11:05:27.176Z",
    "updated_at": "2014-10-14T11:05:27.176Z",
    "_links": {},
    "application": {
      "id": 327,
      "name": "Zendesk",
      "icon_url": "https://dxgv4vuja9avs.cloudfront.net/applications/327/64981f9198413209.png",
      "url": "http://api.flowdock.com/oauth/applications/327"
    },
    "creator": {
      "id": 1,
      "avatar": "https://d2cxspbh1aoie1.cloudfront.net/avatars/f0b4520a6e0001636bf8fc1431af151c",
      "email": "testuser@example.com",
      "name": "User",
      "nick": "User",
      "website": "http://www.example.com/"
    }
  },
  {
    "id": 2,
    "name": "Engineering",
    "url": "https://api.flowdock.com/flows/example/main/sources/2",
    "external_url": "https://acme.example.com/polls/helsinki",
    "created_at": "2014-10-14T11:05:27.007Z",
    "updated_at": "2014-10-14T11:05:27.007Z",
    "_links": {},
    "application": {
      "id": 327,
      "name": "Zendesk",
      "icon_url": "https://dxgv4vuja9avs.cloudfront.net/applications/327/64981f9198413209.png",
      "url": "http://api.flowdock.com/oauth/applications/327"
    },
    "creator": {
      "id": 1,
      "avatar": "https://d2cxspbh1aoie1.cloudfront.net/avatars/f0b4520a6e0001636bf8fc1431af151c",
      "email": "testuser@example.com",
      "name": "User",
      "nick": "User",
      "website": "http://www.example.com/"
    }
  }
]

Get a Source

GET /flows/:organization/:flow/sources/:id

Get a single source.

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Flowdock-User: 2

{
  "id": 2,
  "name": "Engineering",
  "url": "https://api.flowdock.com/flows/example/main/sources/2",
  "external_url": "https://acme.example.com/polls/helsinki"
  "created_at": "2014-10-14T11:05:27.007Z",
  "updated_at": "2014-10-14T11:05:27.007Z",
  "_links": {},
  "application": {
    "id": 327,
    "name": "Zendesk",
    "icon_url": "https://dxgv4vuja9avs.cloudfront.net/applications/327/64981f9198413209.png",
    "url": "http://api.flowdock.com/oauth/applications/327"
  },
  "creator": {
    "id": 1,
    "avatar": "https://d2cxspbh1aoie1.cloudfront.net/avatars/f0b4520a6e0001636bf8fc1431af151c",
    "email": "testuser@example.com",
    "name": "User",
    "nick": "User",
    "website": "http://www.example.com/"
    }
}

Create a Source

POST /flows/:organization/:flow/sources

Create a source for the specified flow. The source will be assigned a flow_token that can be used to push content by the OAuth application to the flow.

OAuth scope requirements

This endpoint is currently only available for OAuth applications with scope integration. The OAuth application will be used as the application attribute of the source.

Name Description
name Required. The name of the source
external_url URL to the external resource or entity that this source represents, e.g. GitHub repository

Example

{
  "name": "Helsinki Lunch Poll",
  "external_url": "https://acme.example.com/polls/helsinki"
}

Response

HTTP/1.1 201 OK
Content-Type: application/json; charset=utf-8
Flowdock-User: 9

{
  "id": 3,
  "name": "Helsinki Lunch Poll",
  "url": "https://api.flowdock.com/flows/example/main/sources/3",
  "external_url": "https://acme.example.com/polls/helsinki",
  "created_at": "2014-10-14T11:06:28.131Z",
  "updated_at": "2014-10-14T11:06:28.131Z",
  "flow_token": "1b609b5253702a0a7ca3607f02642130",
  "_links": {},
  "application": {
    "id": 1,
    "name": "AwesomeApp",
    "icon_url": "https://dxgv4vuja9avs.cloudfront.net/applications/327/64981f9198413209.png",
    "url": "http://api.flowdock.com/oauth/applications/1"
  },
  "creator": {
    "id": 1,
    "avatar": "https://d2cxspbh1aoie1.cloudfront.net/avatars/f0b4520a6e0001636bf8fc1431af151c",
    "email": "testuser@example.com",
    "name": "User",
    "nick": "User",
    "website": "http://www.example.com/"
  }
}

flow_token is only visible in the response of the source creation request. It cannot be retrieved later on.

Update a Source

After a source has been created, two fields can be updated with a PUT request: an error message and the configuration URL of the source. The error message should be used to indicate a problem with the source, and will be displayed for people in the flow. The configuration URL defines where the user is directed to when clicking the configure link next to the source in the flow’s Inbox Settings.

Using normal authentication methods

PUT /flows/:organization/:flow/sources/:id
Name Description
error_message The error message to be displayed for this source. Clear the error with an empty string
configuration_url The URL where users can configure this source

Using the source’s flow_token

The source can also be updated using its unique flow_token. This is not exactly RESTful but is handy when storing the source ID would be unnecessary.

PUT /sources
Name Description
flow_token Required. The token associated with the source
error_message The error message to be displayed for this source. Clear the error with an empty string
configuration_url The URL where users can configure this source

Delete a Source

DELETE /flows/:organization/:flow/sources/:id

Delete a source with the specified id. This will also invalidate the flow_token and prevent the source from posting content to the flow.

Response

HTTP/1.1 204 OK
Content-Type: application/json; charset=utf-8
Flowdock-User: 2