NAV Navigation

Productstash API

shell

Introduction

Welcome to the Productstash API! You can use our API to access Productstash API endpoints, which can be used to view, create and update Ideas, Roadmap Cards, Updates and more.

You can view code examples and response structures in the dark area to the right.

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 committing them to your source control repository.

The main endpoint is:

https://api.productstash.io/v1

Authentication

Productstash uses API keys to allow access to the API. You can register a new API key at our developer portal.

Productstash expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer API_KEY

Workspaces

The Workspace Object

{
"id": "5e8a1026e123d000224361a1",
"title": "RocketShip iOS Mobile App",
"description": "RocketShip for iOS is a mobile app designed to..",
"account": "5c673453d49bf62217537b57",
"slug": "rocketship-ios-mobile-app",
"roadmap": "5f4a1026e123d0002243618s",
"created": "2021-01-19T08:19:48.209Z",
"updated": "2021-01-29T18:14:28.209Z",
}
Parameter Type Description
id string The id of the Workspace
title string The title of the Workspace
description string The description of the Workspace (HTML format)
account string The Account Id that the Workspace belongs to
slug string The URL slug of the Workspace (used for public roadmaps)
roadmap string The Workspace’s Roadmap Id
created string The date at which the Workspace was created
updated string The date at which the Workspace was last updated

Get All Workspaces

curl "https://api.productstash.io/v1/workspaces"
-H "Content-Type: application/json"
-H "Authorization: Bearer API_KEY"

The above command returns JSON structured like this:

{
"success": true,
"results": 10,
"workspaces": [
{
"id": "5e8a1026e123d000224361a1",
"title": "RocketShip iOS Mobile App",
"description": "RocketShip for iOS is a mobile app designed to..",
"account": "5c673453d49bf62217537b57",
"slug": "rocketship-ios-mobile-app",
"roadmap": "5f4a1026e123d0002243618s",
"created": "2021-01-19T08:19:48.209Z",
"updated": "2021-01-29T18:14:28.209Z",
},
{...},
{...}
]

This endpoint retrieves all workspaces for a given account.

HTTP Request

GET https://api.productstash.io/v1/workspaces

Get Workspace

curl "https://api.productstash.io/v1/workspaces/{id}"
-H "Content-Type: application/json"
-H "Authorization: Bearer API_KEY"

The above command returns JSON structured like this:

{
"id": "5e8a1026e123d000224361a1",
"title": "RocketShip iOS Mobile App",
"description": "RocketShip for iOS is a mobile app designed to..",
"account": "5c673453d49bf62217537b57",
"slug": "rocketship-ios-mobile-app",
"roadmap": "5f4a1026e123d0002243618s",
"logo": "https://link-to-image.png",
"created": "2021-01-19T08:19:48.209Z",
"updated": "2021-01-29T18:14:28.209Z",
}

This endpoint retrieves a specific Workspace.

HTTP Request

https://api.productstash.io/v1/workspaces/{id}

URL Parameters

Parameter Description
id The ID of the Workspace to retrieve

Ideas

The Idea Object

{
"id": "5ebre2026e123d000224361a1",
"title": "Improve notifications and email alerts",
"description": "Add more flexibility to the user notifications and provide an easier UI to config",
"workspace": "5e8a1026e123d000224361a1",
"account": "5c673453d49bf62217537b57",
"category": {
"id": "5c97a92ea576c80017fwff4w",
"title": "New idea",
"color": "#ffffff",
"bgcolor": "#1869fb"
},
"created": "2021-01-19T08:19:48.209Z",
"updated": "2021-01-29T18:14:28.209Z",
"completed": false,
"public": true,
"value": 5,
"effort": 4,
"priority": 1,
"archived": false,
"created_by": "Alex Smith",
"votes": 9,
"roadmap_card": "5d881453d49bf62217537b32",
"merged_to": "6fd81453d49bf6221753715g",
"converted_to": "6fd88392t39bf6221753752h",
"duplicated_from": "5fg6692t39bf6221798fj2g",
"merges": ["5fg6692t39bf6221798fj2g", "6fd88392t39bf6221753752h"],
"tags": ["tag1", "tag2", "tag3"],
"comments": [
{
"comment": "Great idea!",
"created_by": "James Williams",
"email": "j_williams@example.com",
"created": "2021-01-22T11:24:56.727Z"
},
{...}
],
"followers": [
{
"email": "j_williams@example.com",
"name": "James Williams"
},
{...}
]
}
Parameter Type Description
id string The id of the Idea
title string The title of the Idea
description string The description of the Idea (HTML format)
workspace string The Workspace Id that the Idea belongs to
account string The Account Id that the Idea belongs to
category object The category of the Idea
created string The date at which the Idea was created
updated string The date at which the Idea was last updated
completed boolean Whether the Idea is complete or not
public boolean When false the Idea will be hidden from public views
value number An integer representing the value of an Idea. Expected values: number between 0-5
effort number An integer representing the effort of an Idea. Expected values: number between 0-5
priority number An integer representing the priority of an Idea. Auto-calculated based on value & effort
archived boolean Controls if an Idea is archived or not
created_by string The name of the user who created the Idea
votes number An integer count of the total number of votes the Idea has received
roadmap_card string The id of the related roadmap card
merged_to string The id of the Idea that it has been merged into
converted_to string The id of the roadmap card that it has been converted into
duplicated_from string The id of the Idea that it has been duplicated from
merges array An array of Idea ids that have been merged with this Idea
tags array An array of strings containing an Idea’s tags
comments array An array of objects containing comments on an Idea
followers array An array of objects containing followers on an Idea

Get All Ideas

curl "https://api.productstash.io/v1/ideas"
-H "Content-Type: application/json"
-H "Authorization: Bearer API_KEY"

The above command returns JSON structured like this:

{
"success": true,
"results": 50,
"totalResults": 100,
"page": 1,
"totalPages": 2,
"ideas": [
{
"id": "5ebre2026e123d000224361a1",
"title": "Improve notifications and email alerts",
"description": "Add more flexibility to the user notifications and provide an easier UI to config",
"workspace": "5e8a1026e123d000224361a1",
"account": "5c673453d49bf62217537b57",
"category": {
"id": "5c97a92ea576c80017fwff4w",
"title": "New idea",
"color": "#ffffff",
"bgcolor": "#1869fb"
},
"created": "2021-01-19T08:19:48.209Z",
"updated": "2021-01-29T18:14:28.209Z",
"completed": false,
"public": true,
"value": 5,
"effort": 4,
"priority": 1,
"archived": false,
"created_by": "Alex Smith",
"votes": 9,
"roadmap_card": "5d881453d49bf62217537b32",
"merged_to": "6fd81453d49bf6221753715g",
"converted_to": "6fd88392t39bf6221753752h",
"duplicated_from": "5fg6692t39bf6221798fj2g",
"merges": ["5fg6692t39bf6221798fj2g", "6fd88392t39bf6221753752h"],
"tags": ["tag1", "tag2", "tag3"],
"comments": [
{
"comment": "Great idea!",
"created_by": "James Williams",
"email": "j_williams@example.com",
"created": "2021-01-22T11:24:56.727Z"
},
{...}
],
"followers": [
{
"email": "j_williams@example.com",
"name": "James Williams"
},
{...}
]
},
{...},
{...}
]

This endpoint retrieves all ideas for a given account.

HTTP Request

GET https://api.productstash.io/v1/ideas

Query Parameters

Name Type Description
workspace_id string Unique Workspace id - if provided, the ideas for this workspace will be returned.
completed boolean Boolean value expecting true or false. If true, completed Ideas will be returned. If false, incomplete Ideas will be returned.
public boolean Boolean value expecting true or false. If true, public Ideas will be returned. If false, private Ideas will be returned.
archived boolean Boolean value expecting true or false. If true, archived Ideas will be returned. If false, active Ideas will be returned.
category string String value expecting a unique Category id - if provided, only Ideas in this category will be returned.
sort string String value that controls the sort order of the results. See Sort Options below.

Sort Options

Name Description
created Expected values: created:asc or created:desc
updated Expected values: updated:asc or updated:desc
rank Expected values: rank:asc or rank:desc
effort Expected values: effort:asc or effort:desc
value Expected values: value:asc or value:desc
page Expected values: 1, 2, etc

Get Idea

curl "https://api.productstash.io/v1/ideas/{id}"
-H "Content-Type: application/json"
-H "Authorization: Bearer API_KEY"

The above command returns JSON structured like this:

{
"id": "5ebre2026e123d000224361a1",
"title": "Improve notifications and email alerts",
"description": "Add more flexibility to the user notifications and provide an easier UI to config",
"workspace": "5e8a1026e123d000224361a1",
"account": "5c673453d49bf62217537b57",
"category": {
"id": "5c97a92ea576c80017fwff4w",
"title": "New idea",
"color": "#ffffff",
"bgcolor": "#1869fb"
},
"created": "2021-01-19T08:19:48.209Z",
"updated": "2021-01-29T18:14:28.209Z",
"completed": false,
"public": true,
"value": 5,
"effort": 4,
"priority": 1,
"archived": false,
"created_by": "Alex Smith",
"votes": 9,
"roadmap_card": "5d881453d49bf62217537b32",
"merged_to": "6fd81453d49bf6221753715g",
"converted_to": "6fd88392t39bf6221753752h",
"duplicated_from": "5fg6692t39bf6221798fj2g",
"merges": ["5fg6692t39bf6221798fj2g", "6fd88392t39bf6221753752h"],
"tags": ["tag1", "tag2", "tag3"],
"comments": [
{
"comment": "Great idea!",
"created_by": "James Williams",
"email": "j_williams@example.com",
"created": "2021-01-22T11:24:56.727Z"
},
{...}
],
"followers": [
{
"email": "j_williams@example.com",
"name": "James Williams"
},
{...}
]
}

This endpoint retrieves a specific Idea.

HTTP Request

GET https://api.productstash.io/v1/ideas/{id}

URL Parameters

Parameter Description
id The ID of the Idea to retrieve

Create Idea

curl "https://api.productstash.io/v1/ideas"
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer API_KEY"
-d `{"workspace_id": "5e8a1026e123d000224361a1", "title": "Awesome new idea", "description":"A bit more detail can go here."}`

The above command returns the inserted Idea structured like this:

{
"id": "5ebre2026e123d000224361a1",
"title": "Awesome new idea",
"description": "A bit more detail can go here.",
"workspace": "5e8a1026e123d000224361a1",
"account": "5c673453d49bf62217537b57",
"category": {
"id": "5c97a92ea576c80017fwff4w",
"title": "New idea",
"color": "#ffffff",
"bgcolor": "#1869fb"
},
"created": "2021-01-29T08:19:48.209Z",
"updated": "2021-01-29T08:19:48.209Z",
"completed": false,
"public": false,
"value": 0,
"effort": 0,
"priority": 0,
"archived": false,
"created_by": "Alex Smith",
"votes": 0
}

This endpoint creates a new idea.

HTTP Request

POST https://api.productstash.io/v1/ideas

Request Body

Parameter Type Description
workspace_id string The id of the workspace that the Idea should be created in required
title string The title of the Idea required
description string The description of the Idea optional
public boolean When false the Idea will be hidden from public views optional
value number An integer representing the value of an Idea. Expected values: number between 0-5 (1 = low, 5 = high) optional
effort number An integer representing the effort of an Idea. Expected values: number between 0-5 (1 = low, 5 = high) optional

Update Idea

curl "https://api.productstash.io/v1/ideas/{id}"
-X PUT
-H "Content-Type: application/json"
-H "Authorization: Bearer API_KEY"
-d `{"title": "Updated title here", "description":"And an updated description can go here."}`

The above command returns JSON structured like this:

{
"success": true,
"updated": true
}

This endpoint updates a specific idea.

HTTP Request

PUT https://api.productstash.io/v1/ideas/{id}

URL Parameters

Parameter Description
ID The ID of the idea to update

Request Body

Parameter Type Description
title string The title of the Idea
description string The description of the Idea
category string The Category Id of the Idea
completed boolean Whether the Idea is complete or not
public boolean When false the Idea will be hidden from public views
value number An integer representing the value of an Idea. Expected values: number between 0-5 (1 = low, 5 = high)
effort number An integer representing the effort of an Idea. Expected values: number between 0-5 (1 = low, 5 = high)
archived boolean Controls if an Idea is archived or not

Delete Idea

curl "https://api.productstash.io/v1/ideas/{id}"
-X DELETE
-H "Content-Type: application/json"
-H "Authorization: Bearer API_KEY"

The above command returns JSON structured like this:

{
"success": true,
"deleted" : true
}

This endpoint deletes a specific Idea.

HTTP Request

DELETE https://api.productstash.io/v1/ideas/{id}

URL Parameters

Parameter Description
ID The ID of the Idea to delete

Roadmap Cards

Coming soon.

Updates

The Update Object

{
"id": "5ebre2026e123d000224361a1",
"title": "Our much anticipated feature has landed!",
"description": "We're excited to announce that our latest feature has finally arrived...",
"workspace": "5e8a1026e123d000224361a1",
"account": "5c673453d49bf62217537b57",
"status": "published",
"category": {
"id": "5c97a92ea576c80017fwff4w",
"title": "New Feature",
"color": "#ffffff",
"bgcolor": "#1869fb"
},
"created": "2021-01-19T08:19:48.209Z",
"updated": "2021-01-29T18:14:28.209Z",
"published": "2021-01-29T18:14:28.209Z",
"completed": false,
"public": true,
"archived": false,
"created_by": "Alex Smith",
"likes": 9,
"dislikes": 1,
"neutrals": 2,
"pinned": true,
"converted_from": "6fd88392t39bf6221753752h",
"roadmap_cards": ["5fg6692t39bf6221798fj2g", "6fd88392t39bf6221753752h"],
"features": ["5c97a92ea576c80017fwff4w"],
"feedback": [
{
"message": "I love this update!!",
"sentiment": "positive",
"created_by": "Alex Smith",
"email": "asmith@example.com",
"created": "2021-01-22T11:24:56.727Z"
},
{...}
],
"comments": [
{
"comment": "Great idea!",
"created_by": "James Williams",
"email": "j_williams@example.com",
"created": "2021-01-22T11:24:56.727Z"
},
{...}
]
}
Parameter Type Description
id string The id of the Update
title string The title of the Update
description string The description of the Update (HTML format)
workspace string The Workspace Id that the Update belongs to
account string The Account Id that the Update belongs to
status string The status of the Update published or draft
category object The category of the Update
created string The date at which the Update was created
updated string The date at which the Update was last updated
published string The date at which the Update was published
completed boolean Whether the Update is complete or not
public boolean When false the Update will be hidden from public views
created_by string The name of the user who created the Update
likes number An integer count of the total number of likes the Update has received
dislikes number An integer count of the total number of dislikes the Update has received
neutrals number An integer count of the total number of neutrals the Update has received
pinned boolean Whether or not the Update is pinned
converted_from string The id of the Roadmap Card that it has been converted from
roadmap_cards array An array of Roadmap Card ids that have been added to the Update
features array An array of Feature ids that have been added to the Update
feedback array An array of objects containing feedback received on the Update
comments array An array of objects containing comments on an Update

Get All Updates

curl "https://api.productstash.io/v1/updates"
-H "Content-Type: application/json"
-H "Authorization: Bearer API_KEY"

The above command returns JSON structured like this:

{
"success": true,
"results": 50,
"totalResults": 100,
"page": 1,
"totalPages": 2,
"updates": [
{
"id": "5ebre2026e123d000224361a1",
"title": "Our much anticipated feature has landed!",
"description": "We're excited to announce that our latest feature has finally arrived...",
"workspace": "5e8a1026e123d000224361a1",
"account": "5c673453d49bf62217537b57",
"status": "published",
"category": {
"id": "5c97a92ea576c80017fwff4w",
"title": "New Feature",
"color": "#ffffff",
"bgcolor": "#1869fb"
},
"created": "2021-01-19T08:19:48.209Z",
"updated": "2021-01-29T18:14:28.209Z",
"published": "2021-01-29T18:14:28.209Z",
"public": true,
"created_by": "Alex Smith",
"likes": 9,
"dislikes": 1,
"neutrals": 2,
"pinned": true,
"converted_from": "6fd88392t39bf6221753752h",
"roadmap_cards": ["5fg6692t39bf6221798fj2g", "6fd88392t39bf6221753752h"],
"features": ["5c97a92ea576c80017fwff4w"],
"feedback": [
{
"message": "I love this update!!",
"sentiment": "positive",
"created_by": "Alex Smith",
"email": "asmith@example.com",
"created": "2021-01-22T11:24:56.727Z"
},
{...}
],
"comments": [
{
"comment": "Great idea!",
"created_by": "James Williams",
"email": "j_williams@example.com",
"created": "2021-01-22T11:24:56.727Z"
},
{...}
]
},
{...},
{...}
]

This endpoint retrieves all updates for a given account.

HTTP Request

GET https://api.productstash.io/v1/updates

Query Parameters

Name Type Description
workspace_id string Unique Workspace id - if provided, the Updates for this workspace will be returned.
public boolean Boolean value expecting true or false. If true, public Updates will be returned. If false, private Updates will be returned.
category string String value expecting a unique Category id - if provided, only Updates in this category will be returned.
status string String value expecting draft or published - if provided, only Updates matching this will be returned.
pinned boolean Boolean value expecting true or false. If true, pinned Updates will be returned. If false, Updates that are not pinned will be returned.
sort string String value that controls the sort order of the results. See Sort Options below.

Sort Options

Name Description
created Expected values: created:asc or created:desc
updated Expected values: updated:asc or updated:desc
published Expected values: published:asc or published:desc
page Expected values: 1, 2, etc

Get Update

curl "https://api.productstash.io/v1/updates/{id}"
-H "Content-Type: application/json"
-H "Authorization: Bearer API_KEY"

The above command returns JSON structured like this:

{
"id": "5ebre2026e123d000224361a1",
"title": "Our much anticipated feature has landed!",
"description": "We're excited to announce that our latest feature has finally arrived...",
"workspace": "5e8a1026e123d000224361a1",
"account": "5c673453d49bf62217537b57",
"status": "published",
"category": {
"id": "5c97a92ea576c80017fwff4w",
"title": "New Feature",
"color": "#ffffff",
"bgcolor": "#1869fb"
},
"created": "2021-01-19T08:19:48.209Z",
"updated": "2021-01-29T18:14:28.209Z",
"published": "2021-01-29T18:14:28.209Z",
"public": true,
"created_by": "Alex Smith",
"likes": 9,
"dislikes": 1,
"neutrals": 2,
"pinned": true,
"converted_from": "6fd88392t39bf6221753752h",
"roadmap_cards": ["5fg6692t39bf6221798fj2g", "6fd88392t39bf6221753752h"],
"features": ["5c97a92ea576c80017fwff4w"],
"feedback": [
{
"message": "I love this update!!",
"sentiment": "positive",
"created_by": "Alex Smith",
"email": "asmith@example.com",
"created": "2021-01-22T11:24:56.727Z"
},
{...}
],
"comments": [
{
"comment": "Great idea!",
"created_by": "James Williams",
"email": "j_williams@example.com",
"created": "2021-01-22T11:24:56.727Z"
},
{...}
]
}

This endpoint retrieves a specific Update.

HTTP Request

GET https://api.productstash.io/v1/updates/{id}

URL Parameters

Parameter Description
id The ID of the Update to retrieve

Create Update

curl "https://api.productstash.io/v1/updates"
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer API_KEY"
-d `{"workspace_id": "5e8a1026e123d000224361a1", "title": "Our much anticipated feature has landed!", "description":"We're excited to announce that our latest feature has finally arrived...","category":"5c97a92ea576c80017fwff4w"}`

The above command returns the inserted Idea structured like this:

{
"id": "5ebre2026e123d000224361a1",
"title": "Our much anticipated feature has landed!",
"description": "We're excited to announce that our latest feature has finally arrived...",
"workspace": "5e8a1026e123d000224361a1",
"account": "5c673453d49bf62217537b57",
"status": "draft",
"category": {
"id": "5c97a92ea576c80017fwff4w",
"title": "New Feature",
"color": "#ffffff",
"bgcolor": "#1869fb"
},
"created": "2021-01-19T08:19:48.209Z",
"updated": "2021-01-29T18:14:28.209Z",
"published": "2021-01-29T23:00:00.000Z",
"public": true,
"created_by": "Alex Smith",
"likes": 0,
"dislikes": 0,
"neutrals": 0,
"pinned": false
}

This endpoint creates a new update.

HTTP Request

POST https://api.productstash.io/v1/updates

Request Body

Parameter Type Description
workspace_id string The id of the workspace that the Update should be created in required
title string The title of the Update required
description string The description of the Update optional
category string The category id of the Update required
published string The published date of the Update in format YYYY-MM-DD optional - defaults to current day
status string The status of the Update optional - defaults to draft
public boolean When false the Update will be hidden from public views optional

Update Update

curl "https://api.productstash.io/v1/updates/{id}"
-X PUT
-H "Content-Type: application/json"
-H "Authorization: Bearer API_KEY"
-d `{"title": "Updated title here", "description":"And an updated description can go here."}`

The above command returns JSON structured like this:

{
"success": true,
"updated": true
}

This endpoint updates a specific idea.

HTTP Request

PUT https://api.productstash.io/v1/updates/{id}

URL Parameters

Parameter Description
ID The ID of the Update to update

Request Body

Parameter Type Description
title string The title of the Update
description string The description of the Update
category string The Category id of the Update
published string The published date of the Update in format YYYY-MM-DD
status string The status of the Update. Expected values draft or published
public boolean When false the Update will be hidden from public views

Delete Update

curl "https://api.productstash.io/v1/updates/{id}"
-X DELETE
-H "Content-Type: application/json"
-H "Authorization: Bearer API_KEY"

The above command returns JSON structured like this:

{
"success": true,
"deleted" : true
}

This endpoint deletes a specific Update.

HTTP Request

DELETE https://api.productstash.io/v1/updates/{id}

URL Parameters

Parameter Description
ID The ID of the Update to delete

Feedback

Coming soon.

Webhooks

Coming soon.

Error Codes

Our API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is invalid.
401 Unauthorized – Your API key is wrong.
403 Forbidden – You do not have access to the requested resource.
404 Not Found – The specified resource could not be found.
429 Too Many Requests – Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Changelog

Date Change
19th April 2021 Public API version 0.0.1 published for early acess users.