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.
Unlink feedback
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 |
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 |
---|---|---|
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. |
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:
- new_feedback: when a new feedback is received or added.
- The JSON body will be the feedback entity.
- feedback_attached: when feedback is added to an idea or story.
- The JSON body will contain the story entity under the
story
key, and the feedback entity under thefeedback
key.
- The JSON body will contain the story entity under the
- new_idea: when a new idea is created or feedback is converted to an idea.
- The JSON body will be the idea entity.
- idea_converted: when an idea is converted into a story.
- The JSON body will contain the story entity under the
item
key.
- The JSON body will contain the story entity under the
- new_story_idea: when an idea is created or added to a story.
- The JSON body will contain the story entity under the
story
key, and the idea under theidea
key.
- The JSON body will contain the story entity under the
- status_changed: when a story changes statuses.
- The JSON body will contain the entity under the
item
key, its user engagements under theengagements
key, and a description of the status change under themovedFromTo
key.
- The JSON body will contain the entity under the
- item_completed: when an idea or story is completed.
- The JSON body will contain the entity under the
item
key and its user engagements under theengagements
key.
- The JSON body will contain the entity under the
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
- The Item object's
task
property was removed in favor of anattached
array containing attached feedback or idea.
Feedback
- The merge endpoint has been removed in favor of attach.
Ideas
- Return type for PUT /ideas now returns the updated idea object.