Introduction

Official libraries for Roadmap API are available in GitHub. Let us know if you’ve built a library for a language we’re not offering. We’re currently building open source API libraries for Go, Node, Python, and C#. Tune in M - F at 1pm EST to follow along as we live code these libraries here.

API Endpoint

https://app.roadmap.space/v1

https://app.roadmap.space/v1

The Roadmap API is organized around REST resources. The URLs are predictable. HTTP verbs are used to indicate data intention and HTTP status codes are used to indicate successes or errors.

We support CORS (cross-originresource sharing) for public endpoints allowing you to call the API from anywhere. We recommend keeping your personal access token safe and do not recommend posting them to public websites or even comitting them to your source control repository.

The main endpoint is:

https://app.roadmap.space/v1

Authentication

Authentication example

curl https://api.roadmap.space/roadmap/widget
  -u apidemo@roadmap.space:api-demo-token

rm := roadmap.New("apidemo@roadmap.space", "api-demo-token")

All requests must include a public access token. You manage your access tokens in Account settings > API. Each user has their own tokens so the API can perform actions on behalf of this specific user. Keep them secret.

Basic authentication is used to authenticate a request.

Format:

user@email.com:public_access_token

Roadmap

Roadmap contains all information needed for the public roadmap and widget.

The roadmap object

Attributes

Name	Type	Description
id	`string`	Unique ID for this roadmap
accountId	`string`	Reference to parent accountId
name	`string`	Name of this roadmap. This is displayed in header of public roadmap
subDomain	`string`	Sub-domain for this roadmap where the suffix `.roadmap.space` will be added.
domain	`string`	Domain to access this public roadmap view
color	`string`	Primary color used on public roadmap to customize call to action elements background color
altColor	`string`	Secondary color used on public roadmap elements like the NEW label
css	`string`	Custom css for the public roadmap
header	`string`	Header in raw format for the public roadmap
footer	`string`	Footer in raw format for the public roadmap
title	`string`	Html meta title value for the public roadmap page
desc	`string`	Html meta description value for the public roadmap
logo	`string`	Path for the logo image used on public roadmap
favicon	`string`	Path for the fav icon used on public roadmap
from	`string`	From name used when sending subscriber notifications of item progress
replyTo	`string`	Email used when sending subscriber notifications of item progress
suject	`string`	Subject of the email sent to subscribers on progress update
body	`string`	Body in raw format of the email sent to subscribers on progress update
analytics	`string`	Google analytics code used on public roadmap
newDays	`number`	Number of days to display item as new on public roadmap
categories	`array`	Array of `string` containing objectives for this roadmap
teams	`array`	Array of `string` containing teams for this roadmap

curl https://app.roadmap.space/v1/roadmaps/1234/widget

returns the ideas currently in widget for this roadmap:

[
  {
    "id":"583f35121818d50b1456ea63",
    "roadmapId":"57b8488bc7899e5cb4337f06",
    "category":"Customer Joy",
    "type":0,
    "column":0,
    "title":"ZenDesk Integration",
    "desc":"A ZenDesk integration...",
    "hidden":false,
    "order":0,
    "completed":false,
    "completedOn":"0001-01-01T00:00:00Z",
    "subscribers":[],
    "clap":0,
    "token":"NTgzZjM1MTIxODE4ZDUwYjE0NTZlYTYzfDBkNTZkNDZhLWU1MGItNDc4MS05NjliLWE2MThjNDkwMzQ0ZQ==",
    "subscribersCount":0,
    "revenue":0,
    "team":"",
    "like":0,
    "comments":[],
    "value":4,
    "effort":2,
    "tasks":[],
    "mockups":[],
    "owner": {
      "first":"Brittany ",
      "last":"Fuller",
      "avatar":"brit.png",
      "via":"web",
      "link":"",
      "original":""
    },
    "published":true,
    "created":"2016-11-30T20:22:42.116Z",
    "updated":"2016-11-30T20:28:40.731Z",
    "deleted":"0001-01-01T00:00:00Z",
    "isDeleted":false
  }
]

This returns the ideas currently dispolayed in the widget.

This endpoint does not need authentication as it is returning publicly available data.

HTTP request

GET https://app.roadmap.space/v1/roadmaps/{id}/widget

Submit feedback

curl -X POST https://app.roadmap.space/v1/roadmaps/feedback

returns HTTP 201 Created if successful

The feedback action is used from our widget to create new user feedback and/or subscribe people to an existing idea.

HTTP request

POST https://app.roadmap.space/v1/roadmaps/feedback

Body

Name	type	Description
id	`string`	Roadmap’s id
user	`object`	Subscriber
title	`string`	Optional: Title for the new user feedback
idea	`string`	Optional: New user feedback idea
voted	`string`	Idea id they want to subscribe to

Items

Everything in Roadmap is an item. User Feedback, Idea, Story, as far as the API is concerned are all treated as items.

When requesting resources the entire item object will be returned.

The item object

Example response

{
  "id":"583f35121818d50b1456ea63",
  "roadmapId":"57b8488bc7899e5cb4337f06",
  "category":"Customer Joy",
  "type":0,
  "column":0,
  "title":"ZenDesk Integration",
  "desc":"A ZenDesk integration...",
  "hidden":false,
  "order":0,
  "completed":false,
  "completedOn":"0001-01-01T00:00:00Z",
  "subscribers":[],
  "clap":0,
  "token":"NTgzZjM1MTIxODE4ZDUwYjE0NTZlYTYzfDBkNTZkNDZhLWU1MGItNDc4MS05NjliLWE2MThjNDkwMzQ0ZQ==",
  "subscribersCount":0,
  "revenue":0,
  "team":"",
  "like":0,
  "comments":[],
  "value":4,
  "effort":2,
  "tasks":[],
  "mockups":[],
  "owner": {
    "first":"Brittany ",
    "last":"Fuller",
    "avatar":"brit.png",
    "via":"web",
    "link":"",
    "original":""
  },
  "published":true,
  "Tags": ["tag-1", "tag-2"],
  "created":"2016-11-30T20:22:42.116Z",
  "updated":"2016-11-30T20:28:40.731Z",
  "deleted":"0001-01-01T00:00:00Z",
  "isDeleted":false
}

Attributes

Name	type	Description
id	`string`	Unique ID for this item
roadmapId	`string`	Reference to parent Roadmap
category	`string`	Objective for this item
type	`number`	An integer representing the item type
column	`number`	An integer representing the column it belongs to
title	`string`	The title for this item
desc	`string`	The raw description for this item
hidden	`boolean`	When `true` the item will not be displayed on public roadmap
order	`number`	An integer representing the display order
completed	`boolean`	Indicate if this item is completed
completedOn	`date`	Date when this item was flagged as completed
subscribers	`array`	Array of Subscriber
clap	`number`	Number of claps recorded for this item
token	`string`	A public token used in public roadmap and widget
subscribersCount	`number`	Number of subscribers for this item
revenue	`number`	The sum of all subscriber’s MRR
team	`string`	Team associated with this item
like	`number`	Number of internal likes
comments	`array`	Array of Comment
value	`number`	Projected value for this item
effort	`number`	Projected effort for this item
tasks	`array`	Array of Task
mockups	`array`	Array of Mockup
owner	`owner`	The owner of this item
published	`boolean`	Indicates if this item is published, draft otherwise
tags	`array`	Array of tags `string`
created	`date`	Creation date for this item
updated	`date`	Last updated date for this item

Public item token id

Some endpoint requires a special public item token id sent as parameter to the URL. The format is a base64 encoded string of the item’s id and item’s token separated by a pipe |:

btoa("item-id-here|item-token-here")

Get item

curl https://app.roadmap.space/v1/items/1234
  -u apidemo@roadmap.space:api-demo-token

returns the item

{
    "id":"583f35121818d50b1456ea63",
    "roadmapId":"57b8488bc7899e5cb4337f06",
    "category":"Customer Joy",
    "type":0,
    "column":0,
    "title":"ZenDesk Integration",
    "desc":"A ZenDesk integration...",
    "hidden":false,
    "order":0,
    "completed":false,
    "completedOn":"0001-01-01T00:00:00Z",
    "subscribers":[],
    "clap":0,
    "token":"NTgzZjM1MTIxODE4ZDUwYjE0NTZlYTYzfDBkNTZkNDZhLWU1MGItNDc4MS05NjliLWE2MThjNDkwMzQ0ZQ==",
    "subscribersCount":0,
    "revenue":0,
    "team":"",
    "like":0,
    "comments":[],
    "value":4,
    "effort":2,
    "tasks":[],
    "mockups":[],
    "owner": {
      "first":"Allison ",
      "last":"Grayce",
      "avatar":"allison.png",
      "via":"web",
      "link":"",
      "original":""
    },
    "published":true,
    "created":"2016-11-30T20:22:42.116Z",
    "updated":"2016-11-30T20:28:40.731Z",
    "deleted":"0001-01-01T00:00:00Z",
    "isDeleted":false
  }

This returns a full item object via a public item token id.

HTTP request

GET https://app.roadmap.space/v1/items/{id}

Parameters

Name	type	Description
id	`string`	Public item token id

User feedback

User feedback contains all the information needed to collect and manage feedback from external sources with Roadmap. For example, if you wanted to add feedback from a 3rd party support desk tool we are not integrated with you could do that with the API.

The feedback object

Example response

{
    "id":"583f35121818d50b1456ea63",
    "roadmapId":"57b8488bc7899e5cb4337f06",
    "type":0,
    "column":0,
    "title":"ZenDesk Integration",
    "desc":"A ZenDesk integration...",
    "hidden":false,
    "order":0,
    "subscribers":[],
    "token":"NTgzZjM1MTIxODE4ZDUwYjE0NTZlYTYzfDBkNTZkNDZhLWU1MGItNDc4MS05NjliLWE2MThjNDkwMzQ0ZQ==",
    "subscribersCount":0,
    "revenue":0,
    "comments":[],
    "owner": {
      "first":"Allison ",
      "last":"Grayce",
      "avatar":"allison.png",
      "via":"web",
      "link":"",
      "original":""
    },
    "created":"2016-11-30T20:22:42.116Z",
    "updated":"2016-11-30T20:28:40.731Z",
    "deleted":"0001-01-01T00:00:00Z",
    "isDeleted":false
  }

See the item object for the description of the attributes.

Get feedback

curl https://app.roadmap.space/v1/feedback/id-here/token-here \
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
f, err := client.Feedback.Get("id-here", "token-here")

returns the user feedback

{
    "id":"583f35121818d50b1456ea63",
    "roadmapId":"57b8488bc7899e5cb4337f06",
    "type":0,
    "column":0,
    "title":"ZenDesk Integration",
    "desc":"A ZenDesk integration...",
    "hidden":false,
    "order":0,
    "subscribers":[],
    "token":"NTgzZjM1MTIxODE4ZDUwYjE0NTZlYTYzfDBkNTZkNDZhLWU1MGItNDc4MS05NjliLWE2MThjNDkwMzQ0ZQ==",
    "subscribersCount":0,
    "revenue":0,
    "comments":[],
    "owner": {
      "first":"Allison ",
      "last":"Grayce",
      "avatar":"allison.png",
      "via":"web",
      "link":"",
      "original":""
    },
    "created":"2016-11-30T20:22:42.116Z",
    "updated":"2016-11-30T20:28:40.731Z",
    "deleted":"0001-01-01T00:00:00Z",
    "isDeleted":false
  }

This returns the user feedback matching the id and token.

HTTP request

GET https://app.roadmap.space/v1/feedback/{id}

Parameters

Name	type	Description
id	`string`	Public item token id

List feedback

curl https://app.roadmap.space/v1/feedback/list/1234 \
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
list, err := client.Feedback.List("roadmap-id-here")

returns the feedback for this roadmap

[
  {
    "id":"58543b3780309d60ef7a690f",
    "roadmapId":"5829ded880309d0420adde36",
    "title":"Unit Test List",
    "token":"c9a74c80-3f0a-45fb-81e6-2531f24bec87",
    "subscribersCount":1,
    "revenue": 950,
    "owner":{"first":"Roadmap","last":"","avatar":"rm.png","via":"web","link":"","original":"Unit Test List"},
    "created":"2016-12-16T14:06:31.28-05:00",
    "isDeleted":false
  }
]

This returns all feedback for a specific roadmap.

HTTP request

GET https://app.roadmap.space/v1/feedback/list/{id}/[archive]

Parameters

Name	type	Description
id	`string`	Roadmap unique id
archive	`string`	Optional: For archived feedback, add `/archive` to the URL

Create a new feedback

curl https://app.roadmap.space/v1/feedback \
  -H "Content-Type: applicaiton/json" \
  -X POST
  -d '{}' \
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
f, err := client.Feedback.Create(&Feedback{RoadmapID: "unique-roadmap-id", Title: "my new feedback"})

returns the created feedback

[
  {
    "id":"58543b3780309d60ef7a690f",
    "roadmapId":"5829ded880309d0420adde36",
    "title":"Unit Test List",
    "token":"c9a74c80-3f0a-45fb-81e6-2531f24bec87",
    "subscribersCount":1,
    "revenue": 950,
    "owner":{"first":"Roadmap","last":"","avatar":"rm.png","via":"web","link":"","original":"Unit Test List"},
    "created":"2016-12-16T14:06:31.28-05:00",
    "isDeleted":false
  }
]

Create a new feedback.

Http request

POST https://app.roadmap.space/v1/feedback

Body

Name	type	Description
roadmapId	`string`	Roadmap unique id.
title	`string`	Feedback title.

Convert feedback to idea

curl -X PUT https://app.roadmap.space/v1/feedback/convert/ \
  -d '{"roadmapId": "12ab", "feedbackId": "ab12", "token": "a-1"}
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
f, err := client.Feedback.Convert("roadmap-id-here", "id-here", "token-here")

returns HTTP 200 on success.

Convert a feedback into an idea.

HTTP request

PUT https://app.roadmap.space/v1/feedback/convert

Body

Name	type	Description
roadmapId	`string`	Roadmap id.
feedbackId	`string`	Feedback id.
token	`string`	Feedback token

Merge feedback into existing idea

curl -X PUT https://app.roadmap.space/v1/feedback/merge \
  -H "Content-Type: application/json" \
  -d '{"id": "feedback-pub-token-id", "targetId": "target-idea-unique-id", "roadmapId": "target-roadmap-unique-id"}'
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
f, err := client.Feedback.Merge("feedback-id", "feedback-token", "target-idea-id", "target-roadmap-id")

returns true on success.

Merge a feedback into an existing idea.

HTTP request

PUT https://app.roadmap.space/v1/feedback/merge

Body

Name	type	Description
id	`string`	Public item token id of source feedback.
targetId	`string`	Target idea unique id.
roadmapId	`string`	Target roadmap unique id.

Update feedback

see Update idea

See Update idea.

Delete feedback

curl -X DELETE https://app.roadmap.space/v1/feedback/pub-item-id-here \
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
err := client.Feedback.Delete("id-here", "token-here")

returns true on success.

This actually archive the feedback. To permanently delete an item, you need to call the force delete item action.

HTTP request

DELETE https://app.roadmap.space/v1/feedback/pub-id-here

Parameters

Name	type	Description
id	`string`	Public item token id.

Ideas

Ideas contain all the information needed to create ideas (backlog). For example, you could programtically add subscribers to an existing idea here or use the API to collaborate on ideas with your team outside of the platform.

The idea object

Example response

{
    "id":"583f35121818d50b1456ea63",
    "roadmapId":"57b8488bc7899e5cb4337f06",
    "category":"Customer Joy",
    "type":0,
    "column":0,
    "title":"ZenDesk Integration",
    "desc":"A ZenDesk integration...",
    "hidden":false,
    "order":0,
    "subscribers":[],
    "token":"NTgzZjM1MTIxODE4ZDUwYjE0NTZlYTYzfDBkNTZkNDZhLWU1MGItNDc4MS05NjliLWE2MThjNDkwMzQ0ZQ==",
    "subscribersCount":0,
    "revenue":0,
    "team":"",
    "like":0,
    "comments":[],
    "value":4,
    "effort":2,
    "mockups":[],
    "owner": {
      "first":"Allison ",
      "last":"Grayce",
      "avatar":"allison.png",
      "via":"web",
      "link":"",
      "original":""
    },
    "published":true,
    "created":"2016-11-30T20:22:42.116Z",
    "updated":"2016-11-30T20:28:40.731Z",
    "deleted":"0001-01-01T00:00:00Z",
    "isDeleted":false
  }

See the item object for the description of the attributes.

Get idea

curl https://app.roadmap.space/v1/idea/id-here/token-here \
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
i, err := client.Ideas.Get("id-here", "token-here")

returns the idea

{
    "id":"583f35121818d50b1456ea63",
    "roadmapId":"57b8488bc7899e5cb4337f06",
    "category":"Customer Joy",
    "type":0,
    "column":0,
    "title":"ZenDesk Integration",
    "desc":"A ZenDesk integration...",
    "hidden":false,
    "order":0,
    "subscribers":[],
    "token":"NTgzZjM1MTIxODE4ZDUwYjE0NTZlYTYzfDBkNTZkNDZhLWU1MGItNDc4MS05NjliLWE2MThjNDkwMzQ0ZQ==",
    "subscribersCount":0,
    "revenue":0,
    "team":"",
    "like":0,
    "comments":[],
    "value":4,
    "effort":2,
    "mockups":[],
    "owner": {
      "first":"Allison ",
      "last":"Grayce",
      "avatar":"allison.png",
      "via":"web",
      "link":"",
      "original":""
    },
    "published":true,
    "created":"2016-11-30T20:22:42.116Z",
    "updated":"2016-11-30T20:28:40.731Z",
    "deleted":"0001-01-01T00:00:00Z",
    "isDeleted":false
  }

This returns the idea matching the id and token.

HTTP request

GET https://app.roadmap.space/v1/ideas/{id}

Parameters

Name	type	Description
id	`string`	Public item token id

List idea

curl https://app.roadmap.space/v1/ideas/list/1234 \
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
p := &roadmap.IdeaListParams{IsArchived: true}
list, err := client.Ideas.List("roadmap-id-here", p)

returns the ideas for this roadmap with optional parameters

[
  {
    "id":"58543b3780309d60ef7a690f",
    "roadmapId":"5829ded880309d0420adde36",
    "column":1,
    "category":"Product vision",
    "title":"Unit Test List",
    "token":"c9a74c80-3f0a-45fb-81e6-2531f24bec87",
    "subscribersCount":1,
    "revenue": 950,
    "owner": {
      "first":"Allison ",
      "last":"Grayce",
      "avatar":"allison.png",
      "via":"web",
      "link":"",
      "original":""
    },
    "clap": 129,
    "subscribersCount":0,
    "revenue":0,
    "like":0,
    "comments":[],
    "value":4,
    "effort":2,
    "created":"2016-12-16T14:06:31.28-05:00",
    "isDeleted":false
  }
]

This returns all ideas for a specific roadmap. You may specify optional URL parameters that indicate if archived ideas are returned instead of active.

/archived: Returns archived ideas.

/all: Returns active, archived and milestone idea types.

HTTP request

GET https://app.roadmap.space/v1/feedback/list/{id}/[type]

Parameters

Name	type	Description
id	`string`	Roadmap unique id
type	`string`	Optional: Either `archived` or `all`.

curl https://app.roadmap.space/v1/ideas/move/{type} \
  -X POST \
  -d `{"id": "unique-id", "roadmapId": "roadmap-id", "token": "idea-token"}`
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
ok, err := client.Ideas.ToWidget("id-here", "roadmap-id", "token")
// or
ok, err := client.Ideas.ToIdea("id-here", "roadmap-id", "token")
// or
ok, err := client.Ideas.SetActive("id-here", "roadmap-id", "token")

returns HTTP 200 on success

You may easily move an idea from state to state with the move action. Use a URL named parameters to indicate the desired state.

/widget: Will set the idea visible on the roadmap widget.

/idea: Will set an idea to its normal state, i.e. remove from widget.

/active: Will un-archive an archived idea.

HTTP request

POST https://app.roadmap.space/v1/ideas/move/{type}

Parameters

Name	type	Description
type	`string`	One of `widget`, `idea` or `active`

Body

Name	type	Description
id	`string`	Idea unique id.
roadmapId	`string`	Roadmap unique id.
token	`string`	Idea token.

Create idea

curl https://app.roadmap.space/v1/ideas \
  -X POST \
  -d `{"roadmapId": "roadmap-id", "title": "new idea"}`
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
idea := &roadmap.Idea{}
idea.RoadmapID = "id-here"
idea.Title = "New idea"
...
idea, err := client.Ideas.Create(idea)

returns the inserted idea on success

Creates a new idea for a specific roadmap.

HTTP request

POST https://app.roadmap.space/v1/ideas

Body

See the idea object

Update idea

curl https://app.roadmap.space/v1/ideas \
  -X PUT \
  -d `{"id": "unique-id", "roadmapId": "roadmap-id", "token": "idea-token", "title": "changed title"}`
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
idea := &roadmap.Idea{}
idea.ID = "id-here"
idea.RoadmapID = "id-here"
idea.Token = "token-here"
idea.Title = "updated title"
ok, err := client.Ideas.Save(idea)

returns HTTP 200 on success

Update an idea or user feedback.

HTTP request

PUT https://app.roadmap.space/v1/ideas

Body

Name	type	Description
id	`string`	Item unique id.
roadmapId	`string`	Roadmap unique id.
token	`string`	Item token.
category	`string`	Objective for this item
title	`string`	The new title for this item
desc	`string`	The new description for this item
value	`number`	Projected value for this item
effort	`number`	Projected effort for this item
published	`boolean`	Indicates if this item is published, draft otherwise

Like idea

curl https://app.roadmap.space/v1/ideas/like/idea-pub-id \
  -X PUT \
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
ok, err := client.Ideas.Like("id-here", "token-here")

returns HTTP 200 on success

Like an idea.

HTTP request

PUT https://app.roadmap.space/v1/ideas/like/{id}

Parameters

Name	type	Description
id	`string`	Public item token id

Delete idea

curl https://app.roadmap.space/v1/ideas/idea-pub-id \
  -X DELETE \
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
ok, err := client.Ideas.Delete("id-here", "token-here")

returns HTTP 200 on success

This actually archive the idea. To permanently delete an item, you need to call the force delete item action.

HTTP request

DELETE https://app.roadmap.space/v1/ideas/{id}

Parameters

Name	type	Description
id	`string`	Public item token id

Stories

Stories contain all the information needed to create roadmap story.

The story object

Example response

{
  "id":"583f35121818d50b1456ea63",
  "roadmapId":"57b8488bc7899e5cb4337f06",
  "category":"Customer Joy",
  "type":1,
  "column":0,
  "title":"ZenDesk Integration",
  "desc":"A ZenDesk integration...",
  "hidden":false,
  "order":0,
  "completed":false,
  "completedOn":"0001-01-01T00:00:00Z",
  "subscribers":[],
  "clap":0,
  "token":"NTgzZjM1MTIxODE4ZDUwYjE0NTZlYTYzfDBkNTZkNDZhLWU1MGItNDc4MS05NjliLWE2MThjNDkwMzQ0ZQ==",
  "subscribersCount":0,
  "revenue":0,
  "team":"",
  "like":0,
  "comments":[],
  "value":4,
  "effort":2,
  "tasks":[],
  "mockups":[],
  "owner": {
    "first":"Brittany ",
    "last":"Fuller",
    "avatar":"brit.png",
    "via":"web",
    "link":"",
    "original":""
  },
  "published":true,
  "Tags": ["tag-1", "tag-2"],
  "created":"2016-11-30T20:22:42.116Z",
  "updated":"2016-11-30T20:28:40.731Z",
  "deleted":"0001-01-01T00:00:00Z",
  "isDeleted":false
}

See the item object for the description of the attributes.

Get story

See [Get item]{#get-item}

List story

See [Get item]{#get-item}.

List story

curl https://app.roadmap.space/v1/stories/1234 \
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
p := &roadmap.IdeaListParams{IsCompleted: true}
list, err := client.Stories.List("roadmap-id-here", p)

returns the stories for this roadmap with optional parameters

[
  {
    "id":"583f35121818d50b1456ea63",
    "roadmapId":"57b8488bc7899e5cb4337f06",
    "category":"Customer Joy",
    "type":0,
    "column":0,
    "title":"ZenDesk Integration",
    "desc":"A ZenDesk integration...",
    "order":0,
    "completed":false,
    "completedOn":"0001-01-01T00:00:00Z",
    "subscribers":[],
    "clap":0,
    "token":"664e7a55-04df-40b1-90e8-d8663d637731",
    "subscribersCount":0,
    "revenue":0,
    "team":"",
    "like":0,
    "value":4,
    "effort":2,
    "tasks":[],
    "mockups":[],
    "owner": {
      "first":"Brittany ",
      "last":"Fuller",
      "avatar":"brit.png",
      "via":"web",
      "link":"",
      "original":""
    },
    "published":true,
    "Tags": ["tag-1", "tag-2"],
    "created":"2016-11-30T20:22:42.116Z",
    "updated":"2016-11-30T20:28:40.731Z",
    "deleted":"0001-01-01T00:00:00Z",
    "isDeleted":false
  }
]

This returns all stories for a specific roadmap. You may specify optional URL parameters that indicate if completed stories are returned instead of active.

/done: Returns completed stories.

HTTP request

GET https://app.roadmap.space/v1/stories/{id}[/done]

Parameters

Name	type	Description
id	`string`	Roadmap unique id.
done	`string`	Optional: Either `/done` or nothing.

Create idea

curl https://app.roadmap.space/v1/stories \
  -X POST \
  -d `{"roadmapId": "roadmap-id", "title": "new story"}`
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
story := &roadmap.Story{}
idea.RoadmapID = "id-here"
idea.Title = "New story"
...
story, err := client.Stories.Create(story)

returns the inserted story on success

Creates a new roadmap story.

HTTP request

POST https://app.roadmap.space/v1/stories

Body

See the story object

Set story as completed

curl https://app.roadmap.space/v1/stories/setcompleted/1234 \
  -X PUT \
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
ok, err := client.Stories.SetAsCompleted("story-id", "story-token")

returns HTTP 200 on success

This tag a story as completed and trigger a notification to the subscribers.

HTTP request

PUT https://app.roadmap.space/v1/stories/setcopleted/{id}

Parameters

Name	type	Description
id	`string`	Public item token id

Update story

curl https://app.roadmap.space/v1/stories \
  -X PUT \
  -d `{"id": "1234", "roadmapId": "1234", "title": "new story title", ...}`
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
story, err := client.Stories.Update(story)

returns HTTP 200 on success

Update a story, you must provide the full story object.

HTTP request

POST https://app.roadmap.space/v1/stories

Body

The full story object

Delete story

curl https://app.roadmap.space/v1/stories/idea-pub-id \
  -X DELETE \
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
ok, err := client.Stories.Delete("id-here", "token-here")

returns HTTP 200 on success

This actually archive the story. Archived stories are automatically cleared after 30 days.

HTTP request

DELETE https://app.roadmap.space/v1/stories/{id}

Parameters

Name	type	Description
id	`string`	Public item token id

Milestones

Milestones are ideas that evolved and merged to a roadmap story. The action of merging an idea to a story milestone brings the subscribers, revenue and like into the story.

The milestone object

{
  "id": "1234",
  "title": "Add Jira integration",
    "done": false,
    "created": "2016/11/5",
    "completed": "2016/12/31",
    "trelloId": "linked trello card id",
    "ghId": "linked GitHub issue id",
    "ideaId": "original idea id",
    "subCount": 219,
    "revenue": 3500,
    "value": 4,
    "effort": 4,
    "objective": "Customer Joy"
}

Attributes

Name	type	Description
id	`string`	Milestone unique id.
title	`string`	MIlestone title.
done	`boolean`	Indicates if the milestone is completed.
created	`date`	Milestone creation date
completed	`date`	Milestone completed date
trelloId	`string`	Indicates if the milestone was pushed to Trello.
ghId	`string`	Indicates if the milestone was pushed to GitHub.
ideaId	`string`	Original idea unique id.
subCount	`number`	Number of subscribers for the linked idea.
revenue	`number`	The sum of all subscriber’s MRR.
value	`number`	Projected value for the linked idea.
effort	`number`	Projected effort for the linked idea.
objective	`string`	Objective for the linked idea.

Merge idea to a milestone

curl https://app.roadmap.space/v1/stories/milestones/merge \
  -X POST \
  -d `{"storyId": "id-here", "ideaId": "id-here", "token": "idea-token"}`
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
ok, err := client.Stories.MergeIdea("story-id", "idea-id", "idea-token")

returns HTTP 200 on success

Merging an idea to a story will create a new milestone for this story. It will also merge the idea subscribers, MRR and images into the target story.

HTTP request

POST https://app.roadmap.space/v1/stories/milestones/merge

Body

Name	type	Description
storyId	`string`	The taget story unique id
ideaId	`string`	The source idea unique id
token	`string`	The source idea public token

Create milestone

curl https://app.roadmap.space/v1/stories/1234/milestones/ \
  -X POST \
  -d `{"title": "milestone title", "done": false}`
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
milestone := &roadmap.Milestone{Title: "new milestone"}
milestone, err := client.Stories.CreateMilestone("story-id", milestone)

returns the inserted milestone

You may also create milestone directly without having an original idea first. This will create a linked idea at the same time.

HTTP request

POST https://app.roadmap.space/v1/stories/{id}/milestones

Parameters

Name	type	Description
id	`string`	Public item token id

Body

Name	type	Description
title	`string`	Milestone title

You may send all attributes of the milestone object.

Send to backlog

curl https://app.roadmap.space/v1/stories/milestones/tobacklog \
  -X PUT \
  -d `{"roadmapId": "id", "storyId": "id", "milestoneId": "id", "ideaId": "id"}`
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
milestone, err := client.Stories.SendToBacklog("rdmp-id", "story-id", "milestone-id", "idea-id")

returns HTTP 200 on success

If you need to transfer a milestone back to an idea you can call this action. Be careful though as this action will return a user feedback to idea. The milestone will be deleted upon success.

HTTP request

PUT https://app.roadmap.space/v1/stories/milestones/tobacklog

Body

Name	type	Description
roadmapId	`string`	The target roadmap unique id.
storyId	`string`	The source story unique id.
milestoneId	`string`	The source milestone unique id.
ideaId	`string`	The target idea unique id.

Set milestone state

curl https://app.roadmap.space/v1/stories/milestones \
  -X PUT \
  -d `{"storyId": "id", "milestoneId": "id", "done": true}`
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
milestone, err := client.Stories.ChangeState("story-id", "milestone-id", true)

returns HTTP 200 on success

Mark a milestone as complete or active.

HTTP request

PUT https://app.roadmap.space/v1/stories/milestones

Body

Name	type	Description
storyId	`string`	The story unique id.
milestoneId	`string`	The milestone unique id.
done	`boolean`	Inidcates if the milestone is complete or not.

Delete a milestone

curl https://app.roadmap.space/v1/stories/1234/milestones/1234 \
  -X DELETE \
  -u "email":"token"

client := roadmap.New("me@roadmap.space", "my-token")
milestone, err := client.Stories.Delete("story-id", "milestone-id")

returns HTTP 200 on success

Permanently delete a milestone and its linked idea / user feedback. This will not remove the subscribers, revenue, images merged to the story.

HTTP request

DELETE https://app.roadmap.space/v1/stories/{id}/milestones/{mid}

Parameters

Name	type	Description
id	`string`	The story unique id.
mid	`string`	The milestone unique id.

Subscribers

Subscribers could be internal or external stakeholders that have expressed an interest in the outcome of feedback, an idea, or a story.

The subscriber object

Example response

{
  "id": "abc123",
  "first": "Dominic",
  "last": "St-Pierre",
  "email": "dominic@roadmap.space",
  "revenue": 35,
  "created": "2016-11-30T20:22:42.116Z"
}

Attributes

Name	type	Description
id	`string`	A unique identifier for this subscriber
first	`string`	Subscriber first name
last	`string`	Subscriber last name
email	`string`	Subscriber email
revenue	`number`	Subscriber MRR
created	`date`	Subscribed date

curl -X POST https://app.roadmap.space/v1/subscribers/1234

returns HTTP 201 Created if successful

Add a new subscriber to an item.

HTTP request

POST https://app.roadmap.space/v1/subscribers/{id}

Parameters

Name	type	Description
id	`string`	Public item token id

Body

Name	type	Description
email	`string`	Subscriber’s email
first	`string`	Optional: Subscriber’s first name
name	`string`	Optional: Subscriber’s last name
revenu	`number (int)`	Optional: Subscriber’s MRR

Clap

curl -X PUT https://app.roadmap.space/v1/subscribers/1234

returns HTTP 200 if successful

Claps are anonymous, for this reason no authentication is required.

HTTP request

PUT https://app.roadmap.space/v1/subscribers/{id}

Parameters

Name	type	Description
id	`string`	Public item token id

Errors

The Roadmap API uses the following error codes:

Error Code	Meaning
400	Bad Request – Your submitted body is missing something required.
401	Unauthorized – Your API key is not valid.
404	Not Found – The specified resource could not be found.
429	Too Many Requests – You’re using too many API calls.
500	Internal Server Error – Doh! Sorry, we had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarially offline for maintenance. Please try again later.

Breaking changes

This page lists the breaking changes from one version to another.

The current version is named: v1.20161202.

If you are using one of our official libraries you may refer to the README of your local copy to check your current version.

Introduction

Authentication

Roadmap

The roadmap object

Get widget ideas

HTTP request

Submit feedback

HTTP request

Body

Items

The item object

Public item token id

Get item

HTTP request

Parameters

User feedback

The feedback object

Get feedback

HTTP request

Parameters

List feedback

HTTP request

Parameters

Create a new feedback

Http request

Body

Convert feedback to idea

HTTP request

Body

Merge feedback into existing idea

HTTP request

Body

Update feedback

Delete feedback

HTTP request

Parameters

Ideas

The idea object

Get idea

HTTP request

Parameters

List idea

HTTP request

Parameters

Move to (widget, idea, active)

HTTP request

Parameters

Body

Create idea

HTTP request

Body

Update idea

HTTP request

Body

Like idea

HTTP request

Parameters

Delete idea

HTTP request

Parameters

Stories

The story object

Get story

List story

List story

HTTP request

Parameters

Create idea

HTTP request

Body

Set story as completed

HTTP request

Parameters

Update story

HTTP request

Body

Delete story

HTTP request

Parameters

Milestones