Developing with Ideanote
Thanks for your interest in developing with Ideanote!
Ideanote is built modular and flexible from the ground up to support a wide range of innovation use-cases. Our easy-to-integrate REST API allows you to create custom innovation workflows for your business - from collecting ideas to managing teams and syncing data.
Introduction
The Ideanote API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. The API is stateless – all requests are validated against an API token.
The API is versioned to ensure backwards compatibility: the current version is v1.
The current base URL of the API is https://api.ideanote.io/v1/.
Note that the URL query parameter field is required for all endpoints.
Use-Cases
The Ideanote API offers a powerful set of tools to integrate idea management capabilities into your business processes and existing infrastructure.
Some common ways of using our API span from integrating Ideanote deep into an application you are developing yourself, to more light use-case of sending of ideas to Ideanote or syncing data between Ideanote and another application.
Take a look at the following examples:
- Idea Submission: Automatically capture ideas from internal communication tools and virtual meetings via the Ideanote API, submitting them directly to Ideanote for evaluation.
- Project Management Integration: Seamlessly transition approved ideas into actionable projects with Ideanote's API, creating tasks or projects in project management tools like Jira.
- In-App Feedback: Direct customer feedback from your applications into Ideanote using the API for structured, customer-driven innovation.
- Business Intelligence: Extract idea submission data for BI analysis, creating detailed reports on innovation ROI, top ideas, and employee contributions with the Ideanote API.
- Employee Recognition: Connect Ideanote with HR systems to automatically reward employees for their contribution to successful ideas, enhancing engagement.
- Data Privacy Compliance: Maintain compliance by using the API to manage user data, including searching, updating, or deleting deactivated users from your central registry.
By leveraging the Ideanote API in these ways, you can create a more integrated, efficient, and engaging innovation ecosystem for your business.
REST API Basics
Ideanote’s API is a REST-based interface, which means that applications make requests to the API by accessing specific URLs using HTTPS. Each request is a single, self-contained operation.
The base URL for all API calls is https://api.ideanote.io/v1/, with specific paths appended to this base URL for accessing different resources. For instance, to list Ideas Collections, the URL extends to include /v1/idea_collections
.
Authentication is essential for using the Ideanote API, requiring an access token to be included in the HTTP header as Authorization: Bearer YOUR_TOKEN
. This ensures secure access to your workspace data scoped to the user who created the access token. Additionally, all API calls must include an Accept: application/json
header, indicating that the data exchange format is JSON, which is the only format supported by the API.
The API is organized around resources, which are identified in the URL and manipulated through HTTP verbs like GET, POST, PUT, and DELETE. These verbs indicate the action you wish to perform, such as querying, adding, updating, or deleting.
Parameters play a significant role in the API's functionality, with query parameters specifying details for GET requests and body data for PUT and POST requests. This allows for nuanced interactions with the API, such as paging through results or updating specific resource data.
Error handling in the Ideanote API utilizes standard HTTP status codes to indicate the success or failure of requests. Common codes include 200
for success, 400
for bad requests, 429
for exceeding usage limits, and 500
for internal server errors.
Ideanote Data Structure
Ideanote's architecture is designed to reflect the hierarchical and collaborative nature of innovation within businesses. This structure supports an organized approach to managing ideas, from inception to execution, within a digital workspace tailored for efficiency.
Below, we delve into the primary components of Ideanote's data structure to help developers navigate and leverage the platform effectively.
Workspaces: A Workspace is the top layer in Ideanote, they organize everything related to innovation in one centralized home for ideas for the business.
Sections: Sections break down the Workspace into more manageable visual areas, such as different departments or topics. This makes it easier to keep innovation organized for the business.
Idea Collections: Idea Collections are where ideas on particular topics are gathered. They include Phases that an idea must pass through, helping to structure the development process from start to finish.
Phases and Ideas: Phases are the steps an idea goes through within a Collection, from conception to completion. Ideas are the fundamental elements here, contributed by users and evolved through comments, likes, and their progression through these Phases. Each idea is based on a custom Form with Idea Fields as defined by the business, sometimes with different Forms for each Idea Collections, depending on context.
Users, Teams, and Ranks: Inside a Workspace, users are the contributors and can be grouped into Teams for collaboration. Users have Ranks such as Workspace Owner, Admin, Member and Guest that can give more or less access to settings, creating Idea Collections and managing content .
Access and Permissions: Access to Idea Collections is managed by sharing settings, not ranks. This means a user's ability to see, add to, or interact with Idea Collections depends on whether it's shared with them or their Team, ensuring the right people can focus on the relevant tasks.
Developers can find more details on user ranks and permissions at Ideanote's help center.
Access to the API
To get started with the Ideanote API, you will need to generate your API Access Token under Settings > Account > API Token in the Ideanote App.
You’ll need to have at least an Admin rank to get access and every user has access to entities and data via the API that they have access to as a user in the Ideanote App.
You can have multiple API Tokens to use across different applications, each can be individually revoked.
Our APIs are free to use for customers on a paid subscription.
Example API Calls
This tutorial will show you how to make your first API call to the Ideanote API and retrieve a list of ideas from an Idea Collection.
Step 1: Generate an Ideanote API Access Token
Here is a step-by-stop tutorial for Authorization
You will need to pass this 43 character long token in an Authorization header of type Bearer Token in all the HTTPS requests you will make to the Ideanote API to access the content defined in your account. Here is an example of an authorization header:
Authorization: Bearer ea5b9e4********************
Step 2: List Idea Collections via the API
Call the Idea Collections endpoint to list all Idea Collections your user has access to.
curl -X GET "https://api.ideanote.io/v1/idea_collections" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
The above command returns JSON structured like this:
[
{
"id": "020166b4-8846-4896-b2ac-9074fd3a1b2c",
"title": "Example Idea Collection",
"question": "How might we improve the coffee?",
"details": null,
"stats": {
"ideas": {
"total": 3
}
},
"cover": {
"url": {
"thumbnail": "https://uploads.staging.ideanote.dev/staging/v1/f985c93c-bcbd-e67f-31e5-d54f965a5fe1/download_original"
}
}
}
]
Step 3: Select an Idea Collection and List Ideas
Call the endpoint to list ideas in a specific Idea Collection. The below example has filled out the id in the format here and contains URL parameters to return metadata and idea fields including field titles, kinds and values.
curl -X GET "https://api.ideanote.io/v1/idea_collections/020166b4-8846-4896-b2ac-9074fd3a1b2c/ideas?fields=id,friendlyId,keywords,status.title,phase.name,fields.{kind,title,value},owner.{firstName}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
Step 4: Processing the JSON Response
The HTTPS response will be a list of ideas formatted as JSON.
Each idea field has an idea field title and value. If you are looking for specific content, for example the description of an idea you can look for the :id with that title and then process the value of that idea field. Idea Fields are listed by their ID to keep the API consistent even if an idea field is renamed in the Ideanote App.
You can identify idea field IDs ahead of time in the Ideanote App under Forms > Fields > Copy ID.
[
{
"id": "38494f31-4edc-414c-8320-e1aa8988e7aa",
"friendlyId": 2,
"keywords": ["bad", "idea", "bad", "idea"],
"status": {
"title": "On Track"
},
"phase": {
"name": "Comment"
},
"fields": [
{
"kind": "LONG_TEXT",
"title": "Description",
"value": "This is a bad idea"
},
{
"kind": "SHORT_TEXT",
"title": "Title",
"value": "Bad Idea"
}
],
"owner": {
"firstName": "Test"
}
},
{
"id": "da011987-cfa9-49fa-b331-bb4ca0b2fa1b",
"friendlyId": 1,
"keywords": ["great", "idea", "great", "idea"],
"status": {
"title": "On Track"
},
"phase": {
"name": "Comment"
},
"fields": [
{
"kind": "SHORT_TEXT",
"title": "Title",
"value": "Great Idea"
},
{
"kind": "LONG_TEXT",
"title": "Description",
"value": "This is a great idea"
}
],
"owner": {
"firstName": "Test"
}
}
]
Authentication
The Ideanote API uses API keys to authenticate requests. All API keys are bound to a specific Ideanote account, so all requests made with the key will only have access to the same content and actions as the account that the key is bound to. You can view and manage your API key on the /settings/account page
curl "<API Endpoint Here>" \
-H "Authorization: Bearer b22d83ae3d28ce49fd1f8633360516"
const result = await fetch("<API Endpoint Here>", {
method: "<HTTP Method Here>",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer b22d83ae3d28ce49fd1f8633360516"
}
});
Make sure to replace
b22d83ae3d28ce49fd1f8633360516
with your API key.
Authorization to the API is performed via HTTP bearer token authentication using the Authorization
header like the following:
Authorization: b22d83ae3d28ce49fd1f8633360516
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Rate limit
The Ideanote employs rate limiting safeguards against bursts of incoming traffic to help maximize its stability. All requests are IP-rate-limited to a maximum of 60 requests per minute and rate limited requests result in a 429 response status code.
Query parameters
Each API endpoint supports these options using URL query parameters:
Query | Default | Example | Description |
---|---|---|---|
text | ?text=foo |
Searches and filters content based on the given text | |
limit | 10 | ?limit=20 |
Limits the total possible amount of entries to retrieve from the endpoint. Max value is 20. |
offset | 0 | ?offset=10 |
Adjusts the offset of items returned |
orderBy | createdAt | ?orderBy=createdAt |
You can order entities by choosing a field on the model to order by |
filter | ?filter={"title":"My Mission"} |
It is possible to build and combine filters to narrow down the received content. | |
fields | ?fields=id,title,question |
Ideanote requires the user of the API to specify a comma-separated list of fields to return. This is done in order to ensure performance and to make populating nested entities possible. |
Fields
Ideanote requires the user of the API to specify a comma-separated list of fields to return. This is done in order to ensure performance and to make populating nested entities possible.
Populating direct fields
?fields=id,title,question
will return the following JSON structure:
{
"id": "abc",
"title": "Title",
"question": "Question"
}
It's possible to populate fields directly on the entity (see example).
You can find an overview of what fields you can populate for each entity. For example, you can find all fields on the Mission entity here
Populating nested fields (dot-syntax)
?fields=id,title,cover.kind,cover.url.original
will return the following JSON structure:
{
"id": "abc",
"title": "Title",
"cover": {
"kind": "IMAGE",
"url": {
"original": "https://...."
}
}
}
It's possible to populate nested fields by using dot-syntax such as cover.url.original
(see example).
Populating multiple nested fields (curly-bracket-syntax)
?fields=id,title,cover.{url.original,kind,fileName}
will return the following JSON structure:
{
"id": "abc",
"title": "Title",
"cover": {
"kind": "IMAGE",
"fileName": "my-file.jpg",
"url": {
"original": "https://...."
}
}
}
In order to more easily populate multiple fields on nested entities it's possible to populate by combining multiple nested fields such as cover.{url.original, kind, fileName}
(see example).
Ordering
You can order entities by choosing a field on the model to order by
Ordering by property with implicit ascending order
?orderBy=firstName
will return the following JSON structure:
[{ "firstName": "A" }, { "firstName": "B" }, { "firstName": "C" }]
It is possible to order by any property of a model such as createdAt
, title
, id
, etc, simply by providing the name of that property to the orderBy
query parameter. Doing so will order the entries in an ascending
order (see example)
Ordering by property with explicit ascending order
?orderBy={"key": "firstName", "direction": "DESC"}
will return the following JSON structure:
[{ "firstName": "C" }, { "firstName": "B" }, { "firstName": "A" }]
Providing a JSON structure with a key
and direction
property such as {"key": "createdAt", "direction": "DESC"}
gives you maximum control of ordering.
- key: The property to order by. Examples:
createdAt
,title
,id
. - direction: The order to sort the entries. Can be:
DESC
: Entries will be ordered in descending order.ASC
: Entries will be ordered in ascending order.
Filters
It is possible to build and combine filters to narrow down the received content.
Simple filtering with implicit EQUALS operator
The following filter will select entities for which the title property matches the value "How might we improve our products" exactly:
?filter={"title":"How might we improve our products"}
Simple filtering with explicit operator
The following filter will select entities for which the title property includes the substring "How might we".
?filter={"title":{"op": "INCLUDES", "value": "How might we"}}
Here is a list of all available operators:
Operator | Description | Example |
---|---|---|
EQUALS | Checks for an exact match | { "title": { "op": "EQUALS", "value": "How might we improve our products" } } |
NOT_EQUALS | The negation of the EQUALS operator | See EQUALS for a comparable example. |
IN | Checks if the property is equal to any of the given values | { "id": { "op": "IN", "value": ["<guid1>","<guid2>"] } } |
IS_NULL | Checks for a nullable value | { "details": { op: "IS_NULL" } } |
IS_NOT_NULL | The negation of the IS_NULL operator | See IS_NULL for a comparable example. |
INCLUDES | Checks if the property includes the provided value | { "title": { "op": "INCLUDES", "value": "How might we" } } |
NOT_INCLUDES | The negation of the INCLUDES operator | See INCLUDES for a comparable example. |
INCLUDES_ELEMENT | Checks if a JSON-property (such as an array) includes the provided value | { "hobbies": { "op": "INCLUDES_ELEMENT", "value": "fishing" } } |
NOT_INCLUDES_ELEMENT | The negation of the INCLUDES_ELEMENT operator | See INCLUDES_ELEMENT for a comparable example. |
LESS_THAN LESS_THAN_OR_EQUALS NOT_LESS_THAN NOT_LESS_THAN_OR_EQUALS GREATER_THAN GREATER_THAN_OR_EQUALS NOT_GREATER_THAN NOT_GREATER_THAN_OR_EQUALS |
All of these performs a comparison with the current value, (typically an ISODate or a number). | { "rank": { op: "LESS_THAN", value: 5000 } } |
Grouped filtering
The following filter selects entities created after 2020-01-01 OR
entities for which the id
property is either "6b8e6531-cf07-4d1f-be39-68ea22d88c0e" or "99e5d8b8-c477-4ce9-812e-9822d18adb99" by combining two filters separated by an OR
operator.
?filter={ "op":"or", "filter":[ { "createdAt": {"op":"GREATER_THAN_OR_EQUALS","value":"2020-01-01T00:00:00.000Z"} }, { "id": { "op":"IN", "value":[ "6b8e6531-cf07-4d1f-be39-68ea22d88c0e", "99e5d8b8-c477-4ce9-812e-9822d18adb99" ] } } ] }
Combined, deep filtering
The following filter combines an outer AND
with an inner OR
. It selects entities for which the question includes "How might we", AND
(either the status is "OPEN" OR the title is "My Mission")
?filter={"op":"and","filter":[{"question":{ "op":"INCLUDES","value":"How might we"}},{"op":"or","filter":[{"status":"OPEN" },{"title":"My Mission"}]}]}
Users
The user object represents members created on the workspace. All users are assigned a rank
such as owner
, admin
or normal
.
The user object
{
"id": "019443b0-fafe-49de-bb6e-0958528d2641",
"createdAt": "2024-05-21T13:46:48.305Z",
"updatedAt": "2024-05-21T13:46:48.322Z",
"activeAt": null,
"firstName": "Test",
"lastName": "Tester",
"email": "test@test.com",
"rank": 5000,
"stats": {
"likes": 0,
"ideas": 3,
"missions": 2,
"assignments": 0
},
"avatar": {
"url": {
"thumbnail": "https://uploads.dev.ideanote.dev/static/icons/beam/v1/124.svg"
}
}
}
Fields
Field | Type | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
id | string |
The unique identifier of the user. | ||||||||||
createdAt | ISODate |
The date when the user was created. | ||||||||||
updatedAt | ISODate |
The date when the user was last updated. | ||||||||||
activeAt | ISODate |
The date when the user was last active. | ||||||||||
firstName | string |
The given name of the user. | ||||||||||
lastName | string |
The surname of the user. | ||||||||||
string |
The email of the user. | |||||||||||
rank | number |
The rank of the user.
|
||||||||||
stats.likes | number |
The number of likes the user has given. | ||||||||||
stats.ideas | number |
The number of ideas the user has created. | ||||||||||
stats.missions | number |
The number of missions the user has created. | ||||||||||
stats.assignments | number |
The number of ideas the user is assigned to. | ||||||||||
avatar | Media | The avatar of the user. |
List users
curl -X GET "https://api.ideanote.io/v1/users?fields=id,email,firstName,lastName,rank,avatar.url.thumbnail" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
const result = await fetch("https://api.ideanote.io/v1/users?fields=id,email,firstName,lastName,rank,avatar.url.thumbnail", {
method: "GET",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const users = await result.json();
The above command returns JSON structured like this:
[
{
"rank": 5000,
"avatar": {
"url": {}
}
},
{
"rank": 2000,
"avatar": {
"url": {}
}
}
]
This endpoint lists users.
HTTP Request
GET /v1/users
Get user
curl -X GET "https://api.ideanote.io/v1/users/019443b0-fafe-49de-bb6e-0958528d2641?fields=id,email,firstName,lastName,rank,avatar.url.thumbnail" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
const result = await fetch("https://api.ideanote.io/v1/users/019443b0-fafe-49de-bb6e-0958528d2641?fields=id,email,firstName,lastName,rank,avatar.url.thumbnail", {
method: "GET",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const user = await result.json();
The above command returns JSON structured like this:
{
"rank": 5000,
"avatar": {
"url": {}
}
}
This endpoint retrieves a specific user.
HTTP Request
GET /v1/users/:user_id
Query Parameters
Parameter | Description |
---|---|
user_id | The ID of the user to retrieve |
Create user
curl -X POST "https://api.ideanote.io/v1/users?fields=id,email,firstName,lastName,rank,avatar.url.thumbnail" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>" \
-d '{"email":"new_user@test.com","firstName":"New","lastName":"User"}'
const result = await fetch("https://api.ideanote.io/v1/users?fields=id,email,firstName,lastName,rank,avatar.url.thumbnail", {
method: "POST",
body: {
"email": "new_user@test.com",
"firstName": "New",
"lastName": "User"
},
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const users = await result.json();
The above command returns JSON structured like this:
{
"rank": 2000,
"avatar": {
"url": {}
}
}
This endpoint creates a new user.
HTTP Request
POST /v1/users
Update user
curl -X PUT "https://api.ideanote.io/v1/users/019443b0-fafe-49de-bb6e-0958528d2641?fields=id,email,firstName,lastName,rank,avatar.url.thumbnail" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>" \
-d '{"firstName":"Bob"}'
const result = await fetch("https://api.ideanote.io/v1/users/019443b0-fafe-49de-bb6e-0958528d2641?fields=id,email,firstName,lastName,rank,avatar.url.thumbnail", {
method: "PUT",
body: {
"firstName": "Bob"
},
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const user = await result.json();
The above command returns JSON structured like this:
{
"rank": 5000,
"avatar": {
"url": {}
}
}
This endpoint updates a specific user
HTTP Request
PUT /v1/users/:user_id
Query Parameters
Parameter | Description |
---|---|
user_id | The ID of the user to update |
Delete user
curl -X DELETE "https://api.ideanote.io/v1/users/019443b0-fafe-49de-bb6e-0958528d2641" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
const result = await fetch("https://api.ideanote.io/v1/users/019443b0-fafe-49de-bb6e-0958528d2641", {
method: "DELETE",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
This endpoint deletes a specific user
HTTP Request
DELETE /v1/users/:user_id
Query Parameters
Parameter | Description |
---|---|
user_id | The ID of the user to delete |
Missions
The mission object represents a mission collection and contains ideas.
The mission object
{
"id": "1678bbb6-61fd-4ba9-841e-6e19e3c0692b",
"createdAt": "2024-05-21T13:46:50.427Z",
"updatedAt": "2024-05-21T13:46:50.528Z",
"title": "My mission",
"question": "How might we improve the coffee?",
"details": null,
"friendlyId": 1,
"archived": false,
"canEdit": true,
"canCreate": true,
"stats": {
"ideas": {
"total": 3,
"days7": 3
}
},
"defaultPhase": {
"name": "Comment",
"kind": "GROW"
},
"team": null,
"cover": {
"url": {
"thumbnail": "https://uploads.dev.ideanote.dev/static/gradients/1024x256/gradient126.jpg"
}
}
}
Fields
Field | Type | Description |
---|---|---|
id | string |
The unique identifier of the mission. |
createdAt | ISODate |
The date when the mission was created. |
updatedAt | ISODate |
The date when the mission was last updated. |
title | string |
The title of the mission |
question | string |
The question of the mission |
details | string |
The details of the mission |
friendlyId | string |
The human readable ID of the mission |
archived | boolean |
Indicates if this mission is archived |
canEdit | boolean |
Indicates if the authorized user can edit this mission |
canCreate | boolean |
Indicates if the authorized user can create ideas in the mission |
stats.ideas.total | number |
The total amount of ideas in the mission |
stats.ideas.days7 | number |
The total amount of ideas in the mission created during the last 7 days |
defaultPhase | Phase | The default phase of ideas in the mission |
team | Team | The team that the mission has been placed in |
cover | Media | The cover image of the mission |
List mission
curl -X GET "https://api.ideanote.io/v1/missions?fields=id,title,question,details,stats.ideas.total,cover.url.thumbnail" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
const result = await fetch("https://api.ideanote.io/v1/missions?fields=id,title,question,details,stats.ideas.total,cover.url.thumbnail", {
method: "GET",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const missions = await result.json();
The above command returns JSON structured like this:
[
{
"details": null,
"stats": {
"ideas": {
"total": 3
}
},
"cover": {
"url": {}
}
}
]
This endpoint lists missions.
HTTP Request
GET /v1/missions
Get mission
curl -X GET "https://api.ideanote.io/v1/missions/1678bbb6-61fd-4ba9-841e-6e19e3c0692b?fields=id,title,question,details,stats.ideas.total,cover.url.thumbnail" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
const result = await fetch("https://api.ideanote.io/v1/missions/1678bbb6-61fd-4ba9-841e-6e19e3c0692b?fields=id,title,question,details,stats.ideas.total,cover.url.thumbnail", {
method: "GET",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const mission = await result.json();
The above command returns JSON structured like this:
{
"details": null,
"stats": {
"ideas": {
"total": 3
}
},
"cover": {
"url": {}
}
}
This endpoint retrieves a specific mission.
HTTP Request
GET /v1/missions/:mission_id
Query Parameters
Parameter | Description |
---|---|
mission_id | The ID of the mission to retrieve |
Create mission
curl -X POST "https://api.ideanote.io/v1/missions?fields=id,title,question,details,stats.ideas.total,cover.url.thumbnail" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>" \
-d '{"question":"How do we improve the coffee?"}'
const result = await fetch("https://api.ideanote.io/v1/missions?fields=id,title,question,details,stats.ideas.total,cover.url.thumbnail", {
method: "POST",
body: {
"question": "How do we improve the coffee?"
},
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const missions = await result.json();
The above command returns JSON structured like this:
{
"title": null,
"details": null,
"stats": {
"ideas": {
"total": 0
}
},
"cover": null
}
This endpoint creates a new mission.
HTTP Request
POST /v1/missions
Update mission
curl -X PUT "https://api.ideanote.io/v1/missions/1678bbb6-61fd-4ba9-841e-6e19e3c0692b?fields=id,title,question,details,stats.ideas.total,cover.url.thumbnail" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>" \
-d '{"question":"How do we improve the cantina?"}'
const result = await fetch("https://api.ideanote.io/v1/missions/1678bbb6-61fd-4ba9-841e-6e19e3c0692b?fields=id,title,question,details,stats.ideas.total,cover.url.thumbnail", {
method: "PUT",
body: {
"question": "How do we improve the cantina?"
},
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const mission = await result.json();
The above command returns JSON structured like this:
{
"details": null,
"stats": {
"ideas": {
"total": 3
}
},
"cover": {
"url": {}
}
}
This endpoint updates a specific mission.
HTTP Request
PUT /v1/missions/:mission_id
Query Parameters
Parameter | Description |
---|---|
mission_id | The ID of the mission to update |
Delete mission
curl -X DELETE "https://api.ideanote.io/v1/missions/1678bbb6-61fd-4ba9-841e-6e19e3c0692b" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
const result = await fetch("https://api.ideanote.io/v1/missions/1678bbb6-61fd-4ba9-841e-6e19e3c0692b", {
method: "DELETE",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
This endpoint deletes a specific mission.
HTTP Request
DELETE /v1/missions/:mission_id
Query Parameters
Parameter | Description |
---|---|
mission_id | The ID of the mission to delete |
Ideas
The idea object
{
"id": "e334370f-bc3c-4d01-9a35-8a57a0914b12",
"createdAt": "2024-05-21T13:46:50.580Z",
"updatedAt": "2024-05-21T13:46:50.826Z",
"friendlyId": 1,
"aiAssisted": false,
"canEdit": true,
"keywords": [
"great",
"idea",
"great",
"idea"
],
"anonymity": null,
"isLiked": false,
"fields": [
{
"kind": "SHORT_TEXT",
"title": "Title",
"value": "Great Idea"
},
{
"kind": "LONG_TEXT",
"title": "Description",
"value": "This is a great idea"
}
],
"stats": {
"likes": {
"total": 0
}
},
"mission": {
"title": "My mission"
},
"owner": {
"email": "test@test.com",
"firstName": "Test"
},
"status": {
"title": "On Track",
"kind": "ACTIVE"
},
"phase": {
"name": "Comment"
}
}
Fields
Field | Type | Description |
---|---|---|
id | string |
The unique identifier of the idea. |
createdAt | ISODate |
The date when the idea was created. |
updatedAt | ISODate |
The date when the idea was last updated. |
friendlyId | number |
The human readable ID of the idea |
aiAssisted | boolean |
Indicates if this idea was created using AI |
canEdit | boolean |
Indicates if the user has edit access to the idea |
keywords | string[] |
The keywords extracted from the idea content |
anonymity | "partial" "full" |
The degree of anonymity that this idea has |
isLiked | boolean |
Indicates if this idea has been liked by the authorized user |
fields.kind | "SHORT_TEXT" "LONG_TEXT" "ATTACHMENTS" "NUMERIC" "CHECKMARK" "SLIDER" "RADIO" "SELECT" "DATETIME" "CODE" "IMAGE_CHOICE" "SCORE" "USER" |
The kind of filled out idea field |
fields.title | string |
The title of filled out idea field |
fields.value | "string" "number" "Media" |
The value of filled out idea field |
stats.likes.total | number |
The total amount of likes of the idea |
mission | Mission | The mission that this idea was created in |
owner | User | The user who created this idea |
status | Status | The status of the idea |
phase | Phase | The current phase of the idea |
List ideas
curl -X GET "https://api.ideanote.io/v1/ideas?fields=id,friendlyId,keywords,status.title,phase.name,fields.{kind,title,value},owner.{firstName}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
const result = await fetch("https://api.ideanote.io/v1/ideas?fields=id,friendlyId,keywords,status.title,phase.name,fields.{kind,title,value},owner.{firstName}", {
method: "GET",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const ideas = await result.json();
The above command returns JSON structured like this:
[
{
"friendlyId": 1,
"keywords": [
null,
null,
null,
null
],
"status": {},
"phase": {},
"fields": [
{},
{}
],
"owner": {}
},
{
"friendlyId": 2,
"keywords": [
null,
null,
null,
null
],
"status": {},
"phase": {},
"fields": [
{},
{}
],
"owner": {}
}
]
This endpoint lists ideas.
HTTP Request
GET /v1/ideas
List ideas in mission
curl -X GET "https://api.ideanote.io/v1/missions/1678bbb6-61fd-4ba9-841e-6e19e3c0692b/ideas?fields=id,friendlyId,keywords,status.title,phase.name,fields.{kind,title,value},owner.{firstName}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
const result = await fetch("https://api.ideanote.io/v1/missions/1678bbb6-61fd-4ba9-841e-6e19e3c0692b/ideas?fields=id,friendlyId,keywords,status.title,phase.name,fields.{kind,title,value},owner.{firstName}", {
method: "GET",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const idea = await result.json();
The above command returns JSON structured like this:
[
{
"friendlyId": 1,
"keywords": [
null,
null,
null,
null
],
"status": {},
"phase": {},
"fields": [
{},
{}
],
"owner": {}
},
{
"friendlyId": 2,
"keywords": [
null,
null,
null,
null
],
"status": {},
"phase": {},
"fields": [
{},
{}
],
"owner": {}
}
]
This endpoint lists ideas.
HTTP Request
GET /v1/missions/:mission_id/ideas
Query Parameters
Parameter | Description |
---|---|
mission_id | The ID of the mission to list ideas |
Get idea
curl -X GET "https://api.ideanote.io/v1/ideas/e334370f-bc3c-4d01-9a35-8a57a0914b12?fields=id,friendlyId,keywords,status.title,phase.name,fields.{kind,title,value},owner.{firstName}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
const result = await fetch("https://api.ideanote.io/v1/ideas/e334370f-bc3c-4d01-9a35-8a57a0914b12?fields=id,friendlyId,keywords,status.title,phase.name,fields.{kind,title,value},owner.{firstName}", {
method: "GET",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const idea = await result.json();
The above command returns JSON structured like this:
{
"friendlyId": 1,
"keywords": [
null,
null,
null,
null
],
"status": {},
"phase": {},
"fields": [
{},
{}
],
"owner": {}
}
This endpoint retrieves a specific idea.
HTTP Request
GET /v1/ideas/:idea_id
Query Parameters
Parameter | Description |
---|---|
idea_id | The ID of the idea to retrieve |
Create idea
curl -X POST "https://api.ideanote.io/v1/ideas?fields=id,friendlyId,keywords,status.title,phase.name,fields.{kind,title,value},owner.{firstName}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>" \
-d '{"mission":"1678bbb6-61fd-4ba9-841e-6e19e3c0692b","Title":"My idea","Description":"This is my idea","Days to Implement":28}'
const result = await fetch("https://api.ideanote.io/v1/ideas?fields=id,friendlyId,keywords,status.title,phase.name,fields.{kind,title,value},owner.{firstName}", {
method: "POST",
body: {
"mission": "1678bbb6-61fd-4ba9-841e-6e19e3c0692b",
"Title": "My idea",
"Description": "This is my idea",
"Days to Implement": 28
},
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const ideas = await result.json();
The above command returns JSON structured like this:
{
"friendlyId": 3,
"keywords": [],
"status": {},
"phase": {},
"fields": [
{},
{},
{
"value": 28
}
],
"owner": {}
}
This endpoint creates a new idea.
HTTP Request
POST /v1/ideas
Update idea
curl -X PUT "https://api.ideanote.io/v1/ideas/e334370f-bc3c-4d01-9a35-8a57a0914b12?fields=id,friendlyId,keywords,status.title,phase.name,fields.{kind,title,value},owner.{firstName}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>" \
-d '{"status":"213889ac-cbf4-404e-bdb5-e1dc528b60e0"}'
const result = await fetch("https://api.ideanote.io/v1/ideas/e334370f-bc3c-4d01-9a35-8a57a0914b12?fields=id,friendlyId,keywords,status.title,phase.name,fields.{kind,title,value},owner.{firstName}", {
method: "PUT",
body: {
"status": "213889ac-cbf4-404e-bdb5-e1dc528b60e0"
},
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const idea = await result.json();
The above command returns JSON structured like this:
{
"friendlyId": 1,
"keywords": [
null,
null,
null,
null
],
"status": {},
"phase": {},
"fields": [
{},
{}
],
"owner": {}
}
This endpoint updates a specific idea.
HTTP Request
PUT /v1/ideas/:idea_id
Query Parameters
Parameter | Description |
---|---|
idea_id | The ID of the idea to update |
Delete idea
curl -X DELETE "https://api.ideanote.io/v1/idea/e334370f-bc3c-4d01-9a35-8a57a0914b12" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
const result = await fetch("https://api.ideanote.io/v1/idea/e334370f-bc3c-4d01-9a35-8a57a0914b12", {
method: "DELETE",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
This endpoint deletes a specific idea.
HTTP Request
DELETE /v1/idea/:idea_id
Query Parameters
Parameter | Description |
---|---|
idea_id | The ID of the idea to delete |
Comments
The comment object represents comments made on ideas.
The comment object
{
"id": "b1ea6cdc-7a14-4035-84c6-8c6e3e336f82",
"createdAt": "2024-05-21T13:46:50.890Z",
"updatedAt": "2024-05-21T13:46:50.890Z",
"text": "Hello World",
"phase": {
"name": "Grow",
"kind": "GROW"
},
"sender": {
"email": "test@test.com",
"firstName": "Test"
}
}
Fields
Field | Type | Description |
---|---|---|
id | string |
The unique identifier of the comment. |
createdAt | ISODate |
The date when the comment was created. |
updatedAt | ISODate |
The date when the comment was last updated. |
text | string |
The content of the comment |
phase | Phase | The phase the comment was created in |
sender | User | The user who created this comment |
List comments for an idea
curl -X GET "https://api.ideanote.io/v1/ideas/e334370f-bc3c-4d01-9a35-8a57a0914b12/comments?fields=id,text,sender.firstName" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
const result = await fetch("https://api.ideanote.io/v1/ideas/e334370f-bc3c-4d01-9a35-8a57a0914b12/comments?fields=id,text,sender.firstName", {
method: "GET",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const comment = await result.json();
The above command returns JSON structured like this:
[
{
"sender": {}
},
{
"sender": {}
},
{
"sender": {}
}
]
This endpoint lists all comments on an idea.
HTTP Request
GET /v1/ideas/:idea_id/comments
Query Parameters
Parameter | Description |
---|---|
idea_id | The ID of the idea to list comments |
Get comment
curl -X GET "https://api.ideanote.io/v1/comments/b1ea6cdc-7a14-4035-84c6-8c6e3e336f82?fields=id,text,sender.firstName" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
const result = await fetch("https://api.ideanote.io/v1/comments/b1ea6cdc-7a14-4035-84c6-8c6e3e336f82?fields=id,text,sender.firstName", {
method: "GET",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const comment = await result.json();
The above command returns JSON structured like this:
{
"sender": {}
}
This endpoint retrieves a specific comment.
HTTP Request
GET /v1/comments/:comment_id
Query Parameters
Parameter | Description |
---|---|
comment_id | The ID of the comment to retrieve |
Update comment
curl -X PUT "https://api.ideanote.io/v1/comments/b1ea6cdc-7a14-4035-84c6-8c6e3e336f82?fields=id,text,sender.firstName" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>" \
-d '{"text":"This is an edited comment"}'
const result = await fetch("https://api.ideanote.io/v1/comments/b1ea6cdc-7a14-4035-84c6-8c6e3e336f82?fields=id,text,sender.firstName", {
method: "PUT",
body: {
"text": "This is an edited comment"
},
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const comment = await result.json();
The above command returns JSON structured like this:
{
"sender": {}
}
This endpoint updates a specific comment.
HTTP Request
PUT /v1/comments/:comment_id
Query Parameters
Parameter | Description |
---|---|
comment_id | The ID of the comment to update |
Delete comment
curl -X DELETE "https://api.ideanote.io/v1/comments/b1ea6cdc-7a14-4035-84c6-8c6e3e336f82" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
const result = await fetch("https://api.ideanote.io/v1/comments/b1ea6cdc-7a14-4035-84c6-8c6e3e336f82", {
method: "DELETE",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
This endpoint deletes a specific comment.
HTTP Request
DELETE /v1/comments/:comment_id
Query Parameters
Parameter | Description |
---|---|
comment_id | The ID of the comment to delete |
Teams
Teams are created on the workspace. Users and missions can be assigned to teams.
The team object
{
"id": "ff02184e-1097-43e2-b434-e295dcb9ac19",
"createdAt": "2024-05-21T13:46:50.236Z",
"updatedAt": "2024-05-21T13:46:50.236Z",
"title": "Designers"
}
Fields
Field | Type | Description |
---|---|---|
id | string |
The unique identifier of the team. |
createdAt | ISODate |
The date when the team was created. |
updatedAt | ISODate |
The date when the team was last updated. |
title | string |
The team name |
List teams
curl -X GET "https://api.ideanote.io/v1/teams?fields=id,title" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
const result = await fetch("https://api.ideanote.io/v1/teams?fields=id,title", {
method: "GET",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const teams = await result.json();
The above command returns JSON structured like this:
[
{},
{}
]
This endpoint lists teams.
HTTP Request
GET /v1/teams
Get team
curl -X GET "https://api.ideanote.io/v1/teams/ff02184e-1097-43e2-b434-e295dcb9ac19?fields=id,title" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
const result = await fetch("https://api.ideanote.io/v1/teams/ff02184e-1097-43e2-b434-e295dcb9ac19?fields=id,title", {
method: "GET",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const team = await result.json();
The above command returns JSON structured like this:
{}
This endpoint retrieves a specific team.
HTTP Request
GET /v1/teams/:team_id
Query Parameters
Parameter | Description |
---|---|
team_id | The ID of the team to retrieve |
Create team
curl -X POST "https://api.ideanote.io/v1/teams?fields=id,title" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>" \
-d '{"title":"Development"}'
const result = await fetch("https://api.ideanote.io/v1/teams?fields=id,title", {
method: "POST",
body: {
"title": "Development"
},
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const teams = await result.json();
The above command returns JSON structured like this:
{}
This endpoint creates a new team.
HTTP Request
POST /v1/teams
Update team
curl -X PUT "https://api.ideanote.io/v1/teams/ff02184e-1097-43e2-b434-e295dcb9ac19?fields=id,title" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>" \
-d '{"title":"Reviewers"}'
const result = await fetch("https://api.ideanote.io/v1/teams/ff02184e-1097-43e2-b434-e295dcb9ac19?fields=id,title", {
method: "PUT",
body: {
"title": "Reviewers"
},
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
const team = await result.json();
The above command returns JSON structured like this:
{}
This endpoint updates a specific team
HTTP Request
PUT /v1/teams/:team_id
Query Parameters
Parameter | Description |
---|---|
team_id | The ID of the team to update |
Delete team
curl -X DELETE "https://api.ideanote.io/v1/teams/ff02184e-1097-43e2-b434-e295dcb9ac19" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <API Token>"
const result = await fetch("https://api.ideanote.io/v1/teams/ff02184e-1097-43e2-b434-e295dcb9ac19", {
method: "DELETE",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer <API Token>",
}
});
This endpoint deletes a specific team
HTTP Request
DELETE /v1/teams/:team_id
Query Parameters
Parameter | Description |
---|---|
team_id | The ID of the team to delete |
Statuses
The status object represent statuses created on the workspace. Each idea points to a status.
The status object
Fields
Field | Type | Description |
---|---|---|
id | string |
The unique identifier of the status. |
createdAt | ISODate |
The date when the status was created. |
updatedAt | ISODate |
The date when the status was last updated. |
title | string |
The title of the status |
text | string |
The description of the status |
kind | "ACTIVE" "COMPLETED" "ARCHIVED" |
The kind of the status |
Media
The media object represents a file uploaded to the server such as a photo or video.
The media object
Fields
Field | Type | Description |
---|---|---|
id | string |
The unique identifier of the media. |
fileName | string |
The name of the file. |
extension | string |
The extension of the file. |
mimeType | string |
The mime type of the file. |
kind | "AUDIO" "IMAGE" "VIDEO" "ICON" "NONE" |
The kind of media. |
url.original | string |
URL pointing to the original file uploaded. |
url.thumbnail | string |
URL pointing to the thumbnail version of this media. |
Phases
Each mission has one or multiple phases. Each idea points to a phase.
The phase object
Fields
Field | Type | Description |
---|---|---|
id | string |
The unique identifier of the phase. |
createdAt | ISODate |
The date when the status was created. |
updatedAt | ISODate |
The date when the phase was last updated. |
kind | "REVIEW" "GROW" "RATE" "ACT" "EXPAND" "DONE" |
The kind of the phase |
name | string |
The name of the phase |
description | string |
The description of the phase |
order | number |
The order of the phase |
stats.ideas | number |
The number of ideas in this phase |