Using the Nestr API

For developers: A technical description on how to integrate with Nestr using our API
Written by Joost Schouten
Updated 9 months ago

Nestr API

The Nestr api allows manipulation of nests from outside the Nestr application. The api can be used to create an integration with other applications, or to easily add nests from anywhere.

There are 2 flavours of the Nestr api available. The first uses the Api access (api) label in Nestr and allows a user to open up any nest for insertions from anywhere as long as the apiKey of that nest is sent along with the api request.
The second flavour allows any kind of manipulation, retrieval or insert, but uses the login credentials of a user to authorize the actions.

API based on labels

The label based api uses an apiKey that is automatically generated when the Api access (api) label is added to nest. This flavour of the api only supports the HTTP PUT and POST methods and thus only supports inserting new nests.
When inserting new nests, next to giving a nest a title, you can also set other characteristics of the new nest:

description set the description of the nest
purpose set the purpose of the nest
labels a comma separated list of labels you want to add to the nest
NOTE: this uses the label id and not the label descriptive name. The id's of the global labels can be found in the Nestr help, the id's of the workspace labels in the workspace settings and the id's of the personal labels can be found on your Profile page.
assign a comma separated list of the usernames (email addresses) to assign to this nest
completed set the nest as completed (you can set a nest as uncompleted by passing in "false" as the value)
due set a due date for the new nest (format YYYYMMDD or YYYYMMDDHHmm), or pass "false" to unset the due date
fieldValues set field values for labels added to the nest. This can either be a javascript array or a comma separated string. The field values are always set using the label code and the field code.

Example: Set the status of the project (project->status) and the api key.
...&fieldValues=project->status:Waiting,api->key:test123
Or in JSON:
{"fieldValues":{"project->status":"Waiting","api->key":"test123"}}


Example (HTTP PUT):
https://app.nestr.io/api/n/[nestId]/New Nest Title?description=Nest+description&labels=api,bug&apiKey=[apiKey]
Example (HTTP POST json):
https://app.nestr.io/api/n/[nestId]/New Nest Title
json payload: {"description":"Nest description","purpose":"Nest purpose","labels":"api,bug","apiKey":"[apiKey]"}

API based on username/password

Advanced users only. Not for the faint of heart.

The full API is only available when you use your normal username and password to login to Nestr. You first need to login via the API and get an authorization token. After that you can use that token to communicate with the full Nestr API.

Logging into the APIYou login to the API via https://app.nestr.io/api/login/ (REST) or by going to /api/authenticate in your browser.

Example:

curl https://app.nestr.io/api/login/ -d "username=test@example.com&password=password"

This will return an authentication token and the userId of the user logging in. Example:

{
  "status": "success",
  "data": {
    "authToken": "7z1Duk73IX5BCuhe6EwRerv_j1xU4ffP8FxUHjuMAGX",
    "userId": "hQ4PXCCzHDH3HDDEz"
  }
}

This should now be used for any subsequent query to the API, by setting the X-User-Id, X-Auth-Token in the headers of the request.
Example:

curl -H "X-Auth-Token: 7z1Duk73IX5BCuhe6EwRerv_j1xU4ffP8FxUHjuMAGX" -H "X-User-Id: hQ4PXCCzHDH3HDDEz" https://app.nestr.io/api/n/DHZL7jdMAftgE8YgB

This request will simply get the nest with ID DHZL7jdMAftgE8YgB.

{
    "_id": "DHZL7jdMAftgE8YgB",
    "parentId": "qsMQNGQbwqTArEnA8",
    "title": "New Nest Title",
    "description": "<p>Nest description</p>",
    "purpose": "test purpose",
    "labels": [
        "bug",
        "project",
        "api"
    ],
    "fieldValues": {
        "project->status": "Current",
        "api->key": "7dZffpOj-bDPBivlrCCAhOFjyo24uSgWYgO6bT037Am"
    },
    "completed": true,
    "properties": {
        "icon": "sitemap",
        "completable": true,
        "color": "#f00",
        "commentable": true
    },
    "createdAt": "2016-01-21T10:51:05.539Z",
    "updatedAt": "2016-01-21T11:44:40.364Z"
}

NOTE: The "title" and "description" fields are rich text fields and could contain HTML codes.

Logging out of the APIYou log out of the API via https://app.nestr.io/api/logout/

Example:

curl https://app.nestr.io/api/logout -X POST -H "X-Auth-Token: 7z1Duk73IX5BCuhe6EwRerv_j1xU4ffP8FxUHjuMAGX" -H "X-User-Id: hQ4PXCCzHDH3HDDEz"

Should return:

{
  "status": "success",
  "data": {
    "message": "You've been logged out!"
  }
}

Using the APIThere are 5 methods you can call on the API to manipulate nests. These are:

GET Get the nest details. See above, "Logging in to the API"
PUT, POST Insert a new nest, below the given nest. PUT works with HTTP query parameters, POST works with JSON data.
PATCH Update the given nest, replacing the given parameters in the nest, but leaving the current values for parameters not passed in this request alone.

This api end point accepts a couple of new parameters, that are not supported by other api end points. These are:
unAssign a comma separated list of the usernames (email addresses) to unassign from this nest
removeLabels a comma separated list of labels you want to remove from the nest

PATCH accepts both HTTP query parameters and POST'ed JSON data
DELETE Delete the given nest and all its children.

See the table under "API based on labels" to see the fields that can be passed into these api end points.

Did this answer your question?