NAV
shell javascript

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:

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.

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.
email string The email of the user.
rank number The rank of the user.

RankDescription
1000Guest
2000Normal
3000Admin
5000Owner
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
shell javascript