Kitemaker API docs logo

Template by CloudCannon

Getting Started Edit

This site describes the REST API available in Kitemaker. This allows you to interact with work items etc as an alternative, though not as fully fledged as the GraphQL developer API.

For questions or comments, please reach out at hi@kitemaker.co or leave us an issue in the repository of this documentation.

Authentication Edit

You need to be authenticated for all API requests. API keys can be created from the command menu Ctrl/Cmd + k » Manage developer settings. Both application tokens and personal access tokens works with this API.

Add the X-API-KEY header to the request with your token.

Manage deeveloper settings

 curl \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/organization

Errors Edit

These are the common errors which can occur. Any errors specific to the endpoint will be mentioned in that section

Code Name Description
400 Bad request Invalid parameters
401 Unauthorized We couldn’t authenticate you
404 Not found The space or work item could not be found
429 Too many requests Rate limit exceeded

All errors will return JSON in the following format:

{
    "errors": [
        {
            "message": "Could not find the specified work item",
            "status": 404,
            "code": "ISSUE_NOT_FOUND"
        }
    ]
}

/organization Edit

Get organization information

Retrieves information about the organization of which the access token is part of

200 Returns the organization info

curl \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/organization

{
    "id": "f221ac0765477000",
    "name": "Kitemaker",
    "createdAt": "2021-12-12T08:25:46.455Z",
    "updatedAt": "2022-07-16T09:23:19.800Z"
}

{
    "errors": [
        {
            "message": "The requested action could not be completed",
            "status": 401,
            "code": "UNAUTHORIZED"
        }
    ]
}

/workitem Edit

Create Work Item

Parameters
spaceKey
The key for the space of the work item
workItemNumber
The work item number

Retrieves a work item specified by the space key and work item number

200 Returns the work item

Error codes

  • 404: Not found
curl \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/workitem?spaceKey=KM&workItemNumber=123

{
  "id": "136975ca1bb5d800",
  "actor": {
    "id": "1335a51729286400",
    "name": "Zapier integration",
    "type": "application"
  },
  "number": 123,
  "title": "My Title",
  "description": "Description",
  "status": {
    "id": "1335a4d06b286401",
    "name": "Done"
  },
  "space": {
    "id": "1335a4d05e286400",
    "name": "Acme"
  },
  "labels": [
    {
      "id": "1369315bce079800",
      "name": "important",
      "color": "e91e63"
    }
  ],
  "effort": "Large",
  "impact": "Medium",
  "createdAt": "2021-11-25T14:46:18.756Z",
  "updatedAt": "2021-11-25T14:46:18.756Z"
}

{
    "errors": [
        {
            "message": "Could not find the specified work item",
            "status": 404,
            "code": "ISSUE_NOT_FOUND"
        }
    ]
}

/workitem Edit

Create Work Item

Parameters
title
The title of the work item
statusId
The status ID (column) where the work item will be created
description
(Optional) The description of the work item. Markdown supported
labelIds[]
(Optional) An array of label IDs to add to the work item
effort
(Optional) The effort to assign to the work item. One of ['small', 'medium', 'large']
impact
(Optional) The impact to assign to the work item. One of ['small', 'medium', 'large']
placement
(Optional) The placement in the status column. One of ['top', 'bottom']. Defaults to 'top'

Creates a new work item and returns the content

201 Returns the work item

Error codes

  • 404: Not found
curl \
  -X POST \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/workitem \
  -d '{"title":"This is my title","statusId": "1adf8dc...", "description": "Lorem ipsum dolor sit amet"}'

{
  "id": "136975ca1bb5d800",
  "actor": {
    "id": "1335a51729286400",
    "name": "Zapier integration",
    "type": "application"
  },
  "number": 123,
  "title": "My Title",
  "description": "Description",
  "status": {
    "id": "1335a4d06b286401",
    "name": "Done"
  },
  "space": {
    "id": "1335a4d05e286400",
    "name": "Acme"
  },
  "labels": [
    {
      "id": "1369315bce079800",
      "name": "important",
      "color": "e91e63"
    }
  ],
  "effort": "Large",
  "impact": "Medium",
  "createdAt": "2021-11-25T14:46:18.756Z",
  "updatedAt": "2021-11-25T14:46:18.756Z"
}

{
    "errors": [
        {
            "message": "The requested action could not be completed",
            "status": 401,
            "code": "UNAUTHORIZED"
        }
    ]
}

/workitem Edit

Update a Work Item

Parameters
id
The ID of the work item
title
(Optional) The title of the work item
statusId
(Optional) The status ID (column) where the work item will be created
description
(Optional) The description of the work item. Markdown supported
labelIds[]
(Optional) An array of label IDs to add to the work item
effort
(Optional) The effort to assign to the work item. One of ['small', 'medium', 'large']
impact
(Optional) The impact to assign to the work item. One of ['small', 'medium', 'large']
placement
(Optional) The placement in the status column. One of ['top', 'bottom']. Defaults to 'top'

Updates a new work item and returns the content. Only provided fields will be updated

200 Returns the updated work item

Error codes

  • 404: Not found
curl \
  -X PUT \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/workitem \
  -d '{"id": "136975ca1bb5d800", "title":"This is my title","statusId": "1adf8dc...", "description": "Lorem ipsum dolor sit amet"}'

{
  "id": "136975ca1bb5d800",
  "actor": {
    "id": "1335a51729286400",
    "name": "Zapier integration",
    "type": "application"
  },
  "number": 123,
  "title": "My Title",
  "description": "Description",
  "status": {
    "id": "1335a4d06b286401",
    "name": "Done"
  },
  "space": {
    "id": "1335a4d05e286400",
    "name": "Acme"
  },
  "labels": [
    {
      "id": "1369315bce079800",
      "name": "important",
      "color": "e91e63"
    }
  ],
  "effort": "Large",
  "impact": "Medium",
  "createdAt": "2021-11-25T14:46:18.756Z",
  "updatedAt": "2021-11-25T14:46:18.756Z"
}

{
    "errors": [
        {
            "message": "The requested action could not be completed",
            "status": 401,
            "code": "UNAUTHORIZED"
        }
    ]
}

/comment Edit

Create a new comment

Parameters
workItemId
The ID of the work item to comment on
body
The body of the comment. Markdown supported

Creates a new comment on the specified work item

201 Returns the created comment

Error codes

  • 404: Not found (the work item was not found)
curl \
  -X POST \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/comment \
  -d '{"workItemId": "136975ca1bb5d800", "body": "Hey there!"}'

{
  "id": "1369791039b5d801",
  "body": "Hey there!",
  "actor": {
    "id": "1335a51729286400",
    "name": "Zapier integration",
    "type": "application"
  },
  "entity": {
    "id": "136975ca1bb5d800",
    "number": 18,
    "space": "ACM",
    "spaceId": "136975ca1bb5d800",
    "title": "My Title"
  },
  "reply": false,
  "threadId": "1369791039b5d800",
  "createdAt": "2021-11-25T14:49:53.313Z",
  "updatedAt": "2021-11-25T14:49:53.313Z"
}

{
    "errors": [
        {
            "message": "The requested action could not be completed",
            "status": 401,
            "code": "UNAUTHORIZED"
        }
    ]
}

/label Edit

Create a new label

Parameters
spaceId
The space ID to create the label in
labelName
The name of the label to create
color
(Optional) The color to assign the label in hte format aa33ff. Defaults to a random color

Creates a new label in the specified space

201 Returns the created label

Error codes

  • 404: Not found (space was not found)
curl \
  -X POST \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/label \
  -d '{"spaceId":"a229cc2147a78000","labelName": "Infrastructure", "color": "ff00aa"}'

{
  "id": "18c20f3a90e21400",
  "name": "Infrastructure",
  "color": "ff00aa",
  "spaceId": "a229cc2147a78000"
}

{
    "errors": [
        {
            "message": "The specified space does not exist",
            "status": 404,
            "code": "SPACE_NOT_FOUND"
        }
    ]
}

/initiative Edit

Parameters
number
The initiative number to retrieve

Retrieves an initiative by its number

200 Returns the initative

Error codes

  • 404: Not found
curl \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/initiative?number=1

[
  {
      "id": "2463901f2d8d2000",
      "number": 1,
      "title": "Hey there",
      "description": "Hello /snippet \n\n",
      "actor": {
          "id": "246388c72bc4f400",
          "name": "@Ole",
          "type": "user"
      },
      "spaces": [
          {
              "id": "24638e578e8d2000",
              "name": "Acme"
          }
      ],
      "labels": [
          {
              "id": "2463903e968d2000",
              "name": "Omg",
              "color": "brown"
          }
      ],
      "effort": null,
      "impact": null,
      "archivedAt": null,
      "updatedAt": "2024-03-19T11:19:26.923Z",
      "createdAt": "2024-03-18T12:04:45.329Z"
  }
]

{
    "errors": [
        {
            "message": "Could not find the specified initiative",
            "status": 404,
            "code": "INITIATIVE_NOT_FOUND"
        }
    ]
}

/initiative Edit

Parameters
title
The title of the initiative
description
(Optional) The description of the initiative. Markdown supported
color
(Optional) The color of the initiative
labelIds[]
(Optional) An array of label IDs to add to the initiative
effortId
(Optional) The effort ID to assign to the initiative
impactId
(Optional) The impact ID to assign to the initiative
spaceIds
(Optional) Space IDs to add to the initiative
roadmapColumnIds
(Optional) Add this initiative to these roadmap columns

Create a new initiative

201 Returns the initative

Error codes

  • 404: Not found
curl \
  -X POST \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/initiative \
  -d '{"title":"This is my title", "description": "Lorem ipsum dolor sit amet"}'

{
  "id": "2463901f2d8d2000",
  "number": 1,
  "title": "Hey there",
  "description": "Hello /snippet \n\n",
  "actor": {
      "id": "246388c72bc4f400",
      "name": "@Ole",
      "type": "user"
  },
  "spaces": [
      {
          "id": "24638e578e8d2000",
          "name": "Acme"
      }
  ],
  "labels": [
      {
          "id": "2463903e968d2000",
          "name": "Omg",
          "color": "brown"
      }
  ],
  "effort": null,
  "impact": null,
  "archivedAt": null,
  "updatedAt": "2024-03-19T11:19:26.923Z",
  "createdAt": "2024-03-18T12:04:45.329Z"
}

{
    "errors": [
        {
            "message": "The requested action could not be completed",
            "status": 401,
            "code": "UNAUTHORIZED"
        }
    ]
}

/feedback Edit

Parameters
number
The feedback number to retrieve

Retrieves an feedback by its number

200 Returns the feedback

Error codes

  • 404: Not found
curl \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/feedback/1

{
    "id": "24ba740439d5a000",
    "organizationId": "246388c6f3c4f400",
    "title": "Creating feedback from REST",
    "person": null,
    "company": null,
    "contents": "Hello there\n",
    "insights": [
        {
            "id": "24ba74042fd5a000",
            "feedbackId": "24ba740439d5a000",
            "createdAt": "2024-04-04T09:01:01.127Z",
            "updatedAt": "2024-04-04T09:01:01.127Z",
            "actor": {
                "id": "246388c72bc4f400",
                "name": "@Ole",
                "type": "user"
            },
            "contents": "Hello there\n",
            "entityIds": [
                "246da190d867d400"
            ]
        }
    ],
    "processed": false,
    "processedAt": null,
    "createdAt": "2024-04-04T09:01:01.088Z",
    "updatedAt": "2024-04-04T09:01:01.088Z"
}

{
    "errors": [
        {
            "message": "Could not find the specified feedback",
            "status": 404,
            "code": "FEEDBACK_NOT_FOUND"
        }
    ]
}

/feedback Edit

Parameters
title
The title of the feedback
personEmail
(Optional) The email of the person which this feedback is from
contents
linkInsightToEntityIds[]
(Optional) Creates insight from this feedback, linking it to a work item

Create a new feedback

201 Returns the feedback

Error codes

  • 404: Not found
curl \
  -X POST \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/feedback \
  -d '{"title":"This is my title"}'

{
  "id": "24ba740439d5a000",
  "organizationId": "246388c6f3c4f400",
  "title": "Creating feedback from REST",
  "person": null,
  "company": null,
  "contents": "Hello there\n",
  "insights": [
      {
          "id": "24ba74042fd5a000",
          "feedbackId": "24ba740439d5a000",
          "createdAt": "2024-04-04T09:01:01.127Z",
          "updatedAt": "2024-04-04T09:01:01.127Z",
          "actor": {
              "id": "246388c72bc4f400",
              "name": "@Ole",
              "type": "user"
          },
          "contents": "Hello there\n",
          "entityIds": [
              "246da190d867d400"
          ]
      }
  ],
  "processed": false,
  "processedAt": null,
  "createdAt": "2024-04-04T09:01:01.088Z",
  "updatedAt": "2024-04-04T09:01:01.088Z"
}

{
    "errors": [
        {
            "message": "The requested action could not be completed",
            "status": 401,
            "code": "UNAUTHORIZED"
        }
    ]
}

/workitems Edit

Get recently updated work items

Parameters
spaceId
The space ID to retrieve work items from
count
The number of work items to retrieve (max 50)

Retrieves a list of recenty updated work items

200 Returns the list of recently updated work items

Error codes

  • 404: Not found (space was not found)
curl \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/recent/workitems?spaceId=0a3abd6aeb71f400&count=10

[
  {
    "id": "136975ca1bb5d800",
    "actor": {
      "id": "1335a51729286400",
      "name": "Zapier integration",
      "type": "application"
    },
    "number": 123,
    "title": "My Title",
    "description": "Description",
    "status": {
      "id": "1335a4d06b286401",
      "name": "Done"
    },
    "space": {
      "id": "1335a4d05e286400",
      "name": "Acme"
    },
    "labels": [
      {
        "id": "1369315bce079800",
        "name": "important",
        "color": "e91e63"
      }
    ],
    "effort": "Large",
    "impact": "Medium",
    "createdAt": "2021-11-25T14:46:18.756Z",
    "updatedAt": "2021-11-25T14:46:18.756Z"
  },
]

{
    "errors": [
        {
            "message": "The specified space does not exist",
            "status": 404,
            "code": "SPACE_NOT_FOUND"
        }
    ]
}

/comments Edit

Get recently updated comments

Parameters
spaceId
The space ID to retrieve comments from
count
The number of comments to retrieve (max 50)

Retrieves recenty updated comments

200 Returns a list of recently updated comments

Error codes

  • 404: Not found (space was not found)
curl \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/recent/comments?spaceId=0a3abd6aeb71f400&count=10

[
  {
    "id": "1369791039b5d801",
    "body": "Hey there!",
    "actor": {
      "id": "1335a51729286400",
      "name": "Zapier integration",
      "type": "application"
    },
    "entity": {
      "id": "136975ca1bb5d800",
      "number": 18,
      "space": "ACM",
      "spaceId": "136975ca1bb5d800",
      "title": "My Title"
    },
    "reply": false,
    "threadId": "1369791039b5d800",
    "createdAt": "2021-11-25T14:49:53.313Z",
    "updatedAt": "2021-11-25T14:49:53.313Z"
  },
]

{
    "errors": [
        {
            "message": "The specified space does not exist",
            "status": 404,
            "code": "SPACE_NOT_FOUND"
        }
    ]
}

/spaces Edit

List all available spaces

Retrieves a list of spaces for an organization. This endpoint is primarily used by the Zapier integration

200 Returns the list of spaces for an organization

Error codes

  • 404: Not found (space was not found)
curl \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/metadata/spaces

[
  {
      "id": "0bbba9fed6573800",
      "label": "A new label"
  },
  {
      "id": "0d185aa8db871400",
      "label": "bug"
  },
]

{
    "errors": [
        {
            "message": "The requested action could not be completed",
            "status": 401,
            "code": "UNAUTHORIZED"
        }
    ]
}

/workitems Edit

List all work items for a space

Parameters
spaceId
The space ID to query

Retrieves a list of work items for a space. This endpoint is primarily used by the Zapier integration

200 Returns the list of work items for the space

Error codes

  • 404: Not found (space was not found)
curl \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/metadata/workitems?spaceId=0a3abd6aeb71f400

[
  {
      "id": "0bbba9fed6573800",
      "label": "Create new work items by pressing C or Shift+C"
  },
  {
      "id": "0d185aa8db871400",
      "label": "Github integration"
  },
]

{
    "errors": [
        {
            "message": "The requested action could not be completed",
            "status": 401,
            "code": "UNAUTHORIZED"
        }
    ]
}

/statuses Edit

List all statuses for a space

Parameters
spaceId
The space ID to query

Retrieves a list of statuses for a space. This endpoint is primarily used by the Zapier integration

200 Returns the list of statuses for the space

Error codes

  • 404: Not found (space was not found)
curl \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/metadata/statuses?spaceId=0a3abd6aeb71f400

[
  {
      "id": "0bbba9fed6573800",
      "label": "In Progress"
  },
  {
      "id": "0d185aa8db871400",
      "label": "Backlog"
  },
]

{
    "errors": [
        {
            "message": "The requested action could not be completed",
            "status": 401,
            "code": "UNAUTHORIZED"
        }
    ]
}

/labels Edit

List all labels for a space

Parameters
spaceId
The space ID to query

Retrieves a list of labels for a space. This endpoint is primarily used by the Zapier integration

200 Returns the list of labels for the space

Error codes

  • 404: Not found (space was not found)
curl \
  -H "Accept: application/json" \ 
  -H "X-API-KEY: <TOKEN>" \
  https://toil.kitemaker.co/developers/rest/v1/metadata/labels?spaceId=0a3abd6aeb71f400

[
  {
      "id": "0a31bd6aeb71f400",
      "label": "Main board"
  },
  {
      "id": "0f63e8cabd046800",
      "label": "User testing"
  }
]

{
    "errors": [
        {
            "message": "The requested action could not be completed",
            "status": 401,
            "code": "UNAUTHORIZED"
        }
    ]
}