NAV
shell go javascript python

Introduction

Official libraries for Roadmap API are available on Github. Let us know if you need a library for a language we're not offering.

API Endpoint

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-origin resource sharing) for public endpoints allowing you to call the API from anywhere. We recommend keeping your personal access tokens 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 my-roadmap-login-email@email.com:my-token
rm := roadmap.New("my-roadmap-login-email@email.com", "my-token")
import { Init } from "roadmap-node";

let roadmap = new Init("my-roadmap-login-email@email.com", "my-token");
import roadmap

roadmap.init("my-roadmap-login-email@email.com", "my-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":[],
  "commentsCount":0,
  "value":4,
  "effort":2,
  "attached":[],
  "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
attached array Array of Item
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 "email":"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

Force delete

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

This permanently deletes a feedback, idea or story. Use with caution!

HTTP request

DELETE https://app.roadmap.space/v1/items/force/{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("my-roadmap-login-email@email.com", "my-token")
f, err := client.Feedback.Get("id-here", "token-here")
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");
client.Items.getById("feedback-id|feedback-token", (err, item) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")
roadmap.items.get_by_id(
  "feedback-id|feedback-token",
  lambda err, item=None: print(err, item)
)

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("my-roadmap-login-email@email.com", "my-token")
list, err := client.Feedback.List("roadmap-id-here")
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

// archive is a boolean parameter. When true it returns the archived feedback
client.Feedback.list("roadmap-id", false, (err, list) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

# archive is a boolean parameter. When true it returns the archived feedback
roadmap.feedback.list(
  "roadmap-id",
  True,
  lambda err, item=None: print(err, item)
)

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
type string Optional: Either archived or all.

Create feedback

curl https://app.roadmap.space/v1/feedback \
  -H "Content-Type: applicaiton/json" \
  -X POST
  -d '{}' \
  -u "email":"token"
client := roadmap.New("my-roadmap-login-email@email.com", "my-token")
f, err := client.Feedback.Create(&Feedback{RoadmapID: "unique-roadmap-id", Title: "my new feedback"})
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

let f = { roadmapId: "roadmap-id", title: "new-feedback", ...};

client.Feedback.add(f, (err, f) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

feedback = {
  "roadmapId": "roadmap-id",
  "title": "new feedback"
}

roadmap.feedback.add(
  feedback,
  lambda err, f=None: print(err, f)
)

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", "id": "ab12", "token": "a-1"}
  -u "email":"token"
client := roadmap.New("my-roadmap-login-email@email.com", "my-token")
ok, err := client.Feedback.Convert(feedback)
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

client.Feedback.convert(feedback, (err, ok) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

roadmap.feedback.convert(
  feedback,
  lambda err, ok=None: print(err, ok)
)

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.
id string Feedback unique id.
token string Feedback token.

Attach to existing idea or story

curl -X POST https://app.roadmap.space/v1/feedback/attach \
  -H "Content-Type: application/json" \
  -d '{"sourceId": "feedback-id", "sourceToken": "feedback-token", "parentId": "parent-id", "parentToken": "parent-token"}' \
  -u "email":"token"
client := roadmap.New("my-roadmap-login-email@email.com", "my-token")
f, err := client.Feedback.Attach("feedback-id", "feedback-token", "parent-id", "parent-token")
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

let p = {
  sourceId: "feedback-id",
  sourceToken: "src-token",
  parentId: "idea-id",
  parentToken: "idea-token",
};

client.Feedback.attachTo(p, (err, feedback) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

p = {
  "sourceId": "feedback-id",
  "sourceToken": "src-token",
  "parentId": "idea-id",
  "parentToken": "idea-token"
}

roadmap.feedback.attach_to(
  p,
  lambda err, feedback=None: print(err, feedback)
)

returns the feedback

Attach a feedback into an existing idea or a story.

HTTP request

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

Body

Name type Description
sourceId string Feedback unique id.
sourceToken string Feedback token.
parentId string Target idea/story unique id.
parentSource string Target idea/story token.

Update feedback

see Update idea

See Update idea.

curl -X DELETE https://app.roadmap.space/v1/feedback/{id}/unlink/{pid} \
  -H "Content-Type: application/json" \
  -u "email":"token"
client := roadmap.New("my-roadmap-login-email@email.com", "my-token")
ok, err := client.Feedback.UnLink("feedback-id", "feedback-token", "parent-id")
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

client.Feedback.unlink(
  "parent-id",
  "feedback-id",
  "feedback-token",
  (err, ok) => {}
);
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

roadmap.feedback.unlink(
  "parent-id",
  "feedback-id",
  "feedback-token",
  lambda err, ok=None: print(err, ok)
)

returns true on success

Removes the feedback from its parent idea or story.

HTTP request

DEELTE https://app.roadmap.space/v1/feedback/{id}/unlink/{pid}

Parameters

Name type Description
id string Public item token id.
pid string Parent idea or story unique id.

Delete feedback

curl -X DELETE https://app.roadmap.space/v1/feedback/pub-item-id-here \
  -u "email":"token"
client := roadmap.New("my-roadmap-login-email@email.com", "my-token")
err := client.Feedback.Delete("id-here", "token-here")
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

client.Feedback.archive("feedback-id", "feedback-token", (err, ok) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

roadmap.feedback.archive(
  "feedback-id",
  "feedback-token",
  lambda err, ok=None: print(err, ok)
)

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("my-roadmap-login-email@email.com", "my-token")
i, err := client.Ideas.Get("id-here", "token-here")
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

client.Items.getById("idea-id|idea-token", (err, list) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

roadmap.items.get_by_id(
  "idea-id|idea-token",
  lambda err, list=None: print(err, list)
)

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("my-roadmap-login-email@email.com", "my-token")
p := &roadmap.IdeaListParams{IsArchived: true}
list, err := client.Ideas.List("roadmap-id-here", p)
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

// 2nd param is a filter with those possible values
// "", "completed", "archived", "all"
client.Ideas.list("roadmap-id", "all", (err, list) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

# 2nd param is a filter with those possible values
# "", "completed", "archived", "all"
roadmap.items.get_by_id(
  "roadmap-id",
  "all",
  lambda err, list=None: print(err, list)
)

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.

/completed: Returns completed ideas.

/archived: Returns archived ideas.

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

HTTP request

GET https://app.roadmap.space/v1/ideas/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("my-roadmap-login-email@email.com", "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")
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

client.Ideas.toWidget("idea-id", "roadmap-id", (err, ok) => {});
// or
client.Ideas.toIdea("idea-id", "roadmap-id", (err, ok) => {});
// or
client.Ideas.setActive("idea-id", "roadmap-id", (err, ok) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

roadmap.ideas.to_widget(
  "idea-id",
  "roadmap-id",
  lambda err, ok=None: print(err, ok)
)
# or
roadmap.ideas.to_idea(
  "idea-id",
  "roadmap-id",
  lambda err, ok=None: print(err, ok)
)
# or
roadmap.ideas.set_active(
  "idea-id",
  "roadmap-id",
  lambda err, ok=None: print(err, ok)
)

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("my-roadmap-login-email@email.com", "my-token")
idea := &roadmap.Idea{}
idea.RoadmapID = "id-here"
idea.Title = "New idea"
...
idea, err := client.Ideas.Create(idea)
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

let idea = { roadmapId: "roadmap-id", title: "new idea", ... };
client.Ideas.add(idea, (err, idea) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

idea = {
  "roadmapId": "roadmap-id",
  "title": "new idea"
}

roadmap.ideas.add(
  idea,
  lambda err, idea=None: print(err, 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("my-roadmap-login-email@email.com", "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)
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

let idea = { id: "idea-id", roadmapId: "roadmap-id", title: "updated title", ...};
client.Ideas.save(idea, (err, idea) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

idea = {
  "id": "idea-id",
  "roadmapId": "roadmap-id",
  "title": "updated title"
}

roadmap.ideas.save(
  idea,
  lambda err, idea=None: print(err, 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("my-roadmap-login-email@email.com", "my-token")
ok, err := client.Ideas.Like("id-here", "token-here")
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

client.Ideas.like("idea-id", "idea-token", (err, ok) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

roadmap.ideas.like(
  "idea-id",
  "idea-token",
  lambda err, ok=None: print(err, ok)
)

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("my-roadmap-login-email@email.com", "my-token")
ok, err := client.Ideas.Delete("id-here", "token-here")
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

client.Ideas.archive("idea-id", "idea-token", (err, ok) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

roadmap.ideas.archive(
  "idea-id",
  "idea-token",
  lambda err, ok=None: print(err, ok)
)

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

curl https://app.roadmap.space/v1/stories/1234 \
  -u "email":"token"
client := roadmap.New("my-roadmap-login-email@email.com", "my-token")
p := &roadmap.StoryListParams{RoadmapID: "roadmap-id-here", Completed: false}
list, err := client.Stories.List(p)
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

// active roadmap stories
client.Stories.list("roadmap-id", (err, list) => {});
// completed roadmap stories
client.Stories.done("roadmap-id", (err, list) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

# active roadmap stories
roadmap.stories.list(
  "roadmap-id",
  lambda err, list=None: print(err, list)
)
# completed roadmap stories
roadmap.stories.done(
  "roadmap-id",
  lambda err, list=None: print(err, list)
)

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 story

curl https://app.roadmap.space/v1/stories \
  -X POST \
  -d '{item object properties}' \
  -u "email":"token"
client := roadmap.New("my-roadmap-login-email@email.com", "my-token")
story := &roadmap.Story{}
story.RoadmapID = "id-here"
story.Title = "New story"
...
story, err := client.Stories.Create(story)
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");
let story = { roadmapId: "roadmap-id", title: "new story", ... };
client.Stories.add(story, (err, story) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

story = {
  "roadmapId": "roadmap-id",
  "title": "new story"
}

roadmap.stories.add(
  story,
  lambda err, story=None: print(err, 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

Create idea

curl https://app.roadmap.space/v1/stories/{story-id}/ideas \
  -X POST \
  -d '{idea object properties}' \
  -u "email":"token"
client := roadmap.New("my-roadmap-login-email@email.com", "my-token")
idea := &roadmap.Idea{}
idea.RoadmapID = "id-here"
idea.Title = "New idea"
...
story, err := client.Stories.AddIdea("story-id", "story-token", idea)
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

let idea = { roadmapId: "roadmap-id", title: "new idea title", ... };
client.Stories.addIdea("story-id", "story-token", idea, (err, idea) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

idea = {
  "roadmapId": "roadmap-id",
  "title": "new idea"
}

roadmap.stories.addIdea(
  "story-id",
  "story-token",
  idea,
  lambda err, idea=None: print(err, idea)
)

returns the inserted idea on success

Creates and attaches a new idea to a story.

HTTP request

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

Parameters

Name type Description
id string Public item token id

Body

See the idea object

Attach

curl https://app.roadmap.space/v1/stories/ideas \
  -X POST \
  -d '{"roadmapId": "1234", "parentId": "1234", "id": "attached-id", "token": "attached-token"}' \
  -u "email":"token"
client := roadmap.New("my-roadmap-login-email@email.com", "my-token")
p := roadmap.StoryAttachItem{RoadmapID: "roadmap-id",
  ParentID: "story-id",
  ID: "attached-id",
  Token: "attached-token",
}
idea, err := client.Stories.Attach(p)
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

let p = {
  roadmapId: "rdmp-id",
  parentId: "story-id",
  id: "source-id",
  token: "source-token"
};
client.Stories.attachIdea(p, (err, item) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

p = {
  "roadmapId": "rdmp-id",
  "parentId": "story-id",
  "id": "source-id",
  "token": "source-token"
}

roadmap.stories.attach_idea(
  p,
  lambda err, item=None: print(err, item)
)

returns the attached item on success.

Attaches an existing feedback or idea to a story.

HTTP request

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

Body

Name type Description
roadmapId string Roadmap unique id.
parentId string Story unique id.
id string Feedback or idea unique id.
token string Feedback or idea token.

Set story as completed

curl https://app.roadmap.space/v1/stories/setcompleted/1234 \
  -X PUT \
  -u "email":"token"
client := roadmap.New("my-roadmap-login-email@email.com", "my-token")
ok, err := client.Stories.SetAsCompleted("story-id", "story-token")
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

client.Stories.setAsCompleted("story-id", "story-token", true, (err, ok) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

roadmap.stories.set_as_completed(
  "story-id",
  "story-token",
  lambda err, ok=None: print(err, ok)
)

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("my-roadmap-login-email@email.com", "my-token")
story, err := client.Stories.Update(story)
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

client.Stories.save(story, (err, story) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

roadmap.stories.save(
  story,
  lambda err, story=None: print(err, 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("my-roadmap-login-email@email.com", "my-token")
ok, err := client.Stories.Delete("id-here", "token-here")
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

client.Stories.remove("story-id", "story-token", (err, ok) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

roadmap.stories.remove(
  "story-id",
  "story-token",
  lambda err, ok=None: print(err, ok)
)

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

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
revenue 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

Users

Users are people that viewed, liked or followed your roadmap stories or ideas. We keep track of their engagements and actions on a dedicated user page.

The user object

Example response

{
  "first" : "Dominic",
  "email" : "dominic@stpierre.com",
  "accountId" : "1234567",
  "roadmaps" : [
    "456789123"
  ],
  "lastSeen" : "2017-06-30T17:27:56.08Z",
  "last" : "St-Pierre",
  "via" : "roadmap-id-here",
  "session" : 15,
  "custom" : {},
  "userId" : "your-internal-user-id",
  "unsubscribed" : false,
  "engagements" : {},
  "following" : 3,
  "revenue" : 55,
  "updated" : "2017-06-30T17:27:56.08Z",
  "company" : "Company Name",
  "id" : "roadmap-unique-id",
  "deleted" : "0001-01-01T00:00:00Z",
  "created" : "2017-03-08T19:08:36.254Z",
  "feedback" : 3,
  "tags" : [],
  "firstSeen" : "2017-03-08T19:08:36.254Z",
  "clap" : 0,
  "isDeleted" : false,
  "activities" : [],
}

Attributes

Name type Description
first string User's first name.
email string User's email.
accountId string Unique account id.
roadmaps array List of roadmap ids this user engaged with.
lastSeen date When we've last seen this user.
last string User's last name.
via string Roadmap id where we've seen this user for first time.
session number Number of sessions we've seen this user.
custom object Custom attributes you can attached to a user.
userId string Your unique id for this user.
unsubscribed boolean Is this user unsubscribed.
engagements object Engagement object.
following number Number of item this user is following.
revenue number Revenue you sent us about this user.
updated date Last time we've updated this user.
company string User's company name.
id string User unique id.
deleted date Date of deletion.
created date Creation date.
feedback* number How many feedback this user gave.
tags array List of tag string for this user.
firstSeen date Date we've first seen this user.
clap number How many claps for your items.
isDeleted boolean Is this user deleted.
activities array Activities for this user.

Webhooks

Webhooks allow you to subscribe to certain key events that happen inside Roadmap. For example, when a story's status is changed or when an idea or story is completed. You may opt-in to receive an HTTP POST containing a JSON payload with related information regarding the event and target entities.

The webhook object

Example response

{
  "id": "unique_webhook_id",
  "accountId": "your_account_id",
  "event": "status_changed",
  "targetUrl": "https://yourdomain.com/some/url",
  "active": true,
  "created": "2018-04-02T07:32:21"
}

Attributes

Name type Description
id string Unique ID for this webhook.
accountId string Your account unique id.
event string One of webhook events.
targetUrl strring An URL where we will send an HTTP POST.
active boolean Is this webhook active.
created date Creation date for this webhook.

Webhook events

You may subscribe to the following webhook events:

Get webhooks

curl https://app.roadmap.space/v1/webhooks \
  -u "email":"token"
client := roadmap.New("my-roadmap-login-email@email.com", "my-token")
webhooks, err := client.Webhooks.List()
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

client.Webhooks.list((err, results) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

roadmap.webhooks.list(
  lambda err, result=None: print(err, result)
)

returns a list of webhook subscriptions

[
  {
    "id": "unique_webhook_id",
    "accountId": "your_account_id",
    "event": "status_changed",
    "targetUrl": "https://yourdomain.com/some/url",
    "active": true,
    "created": "2018-04-02T07:32:21"
  }
]

This returns a list of all webhooks registered for an account.

HTTP request

GET https://app.roadmap.space/v1/webhooks

Create webhook

curl -X POST -d '{"target_url": "https://me.com", "event": "status_changed"}' \
  -u "email":"token" \
    https://app.roadmap.space/v1/webhooks
client := roadmap.New("my-roadmap-login-email@email.com", "my-token")
err := client.Webhooks.Create("https://me.com", "status_changed")
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

client.Webhooks.create("https://me.com", "status_changed", (err, ok) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

story = {
  "roadmapId": "roadmap-id",
  "title": "new story"
}

roadmap.webhooks.create(
  "https://me.com",
  "status_changed"
  lambda err, ok=None: print(err, ok)
)

returns HTTP 200 on success

Creates a new webhook.

HTTP request

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

Body

Name type Description
target_url string URL where Roadmap should send HTTP POST data.
event string One of the webhook events.

Cancel a webhook

curl -X POST -d '{"target_url": "https://me.com"}' \
  -u "email":"token" \
    https://app.roadmap.space/v1/webhooks/cancel
client := roadmap.New("my-roadmap-login-email@email.com", "my-token")
err := client.Webhooks.Cancel("https://me.com")
import { Init } from "roadmap-node";
let client = new Init("my-roadmap-login-email@email.com", "my-token");

client.Webhooks.cancel("https://me.com", (err, ok) => {});
import roadmap
roadmap.init("my-roadmap-login-email@email.com", "my-token")

roadmap.webhooks.cancel(
  "https://me.com",
  lambda err, ok=None: print(err, ok)
)

returns HTTP 200 on success

Deletes a webhook subscription.

HTTP request

POST https://app.roadmap.space/v1/webhooks/cancel

Body

Name type Description
target_url string URL where Roadmap should send HTTP POST data.

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.2.0.

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

Breaking changes since last version: v1.20161202

Item

Feedback

Ideas