NAV Navbar
Logo
shell go

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

Get widget ideas

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.

Move to (widget, idea, active)

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

Subscribe

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.