Skip to main content
Help centre

The Taskshire API

Read and change tasks from your own code, and get a signed message whenever something changes.

Who this is for: Developers and technical teammates who connect Taskshire to other systems.

What you get

  • A REST API that lets your code read and change tasks in the projects you work on: list and filter tasks, create them, update them, move them between stages, and add comments and checklist items.
  • Webhooks that send a signed JSON message to your server whenever a task is created, updated, moved, commented on, published or deleted.

Prefer not to write code? See Zapier, Make and other automation tools.

The basics

What Details
Base URL https://YOUR-TASKSHIRE/api/v1
Format JSON in, JSON out. Send Accept: application/json.
Authentication Authorization: Bearer YOUR-TOKEN
Times ISO 8601. Responses are always in UTC.
Rate limit 120 requests a minute per person, across all their tokens. Above that you get 429 with a Retry-After header.

The API tokens section on your profile page shows the exact base URL for your Taskshire.

Get a token

  1. Select your name at the top right, then Profile and preferences.
  2. Scroll down to API tokens.
  3. Give the token a Name, choose Read only or Read and write, and choose when it Expires after.
  4. Select Create token, then copy it. It’s only shown once.

A token acts as you. It has your roles on every project you belong to, and every change goes through the same permission checks as the app. Read only tokens can use GET requests; Read and write tokens can use everything. Revoke stops a token straight away.

Warning

Keep tokens out of code repositories, chat and email. Tokens start with tsk_, which helps secret scanners spot them if one leaks.

Quick start

Check your token works:

curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
  https://YOUR-TASKSHIRE/api/v1/me

List your projects, then the tasks waiting in one stage:

curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
  https://YOUR-TASKSHIRE/api/v1/projects

curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
  "https://YOUR-TASKSHIRE/api/v1/projects/dark-queen/tasks?stage=internal_review&assignee=me"

Create a task:

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  https://YOUR-TASKSHIRE/api/v1/projects/dark-queen/tasks \
  -d '{"title": "Launch trailer", "brief": "Cut a 30-second trailer.", "due_at": "2026-11-01"}'

Wherever a path has {project}, you can use the project’s id or its short name (dark-queen). Wherever it has {task}, you can use the task’s id, its reference (DQS-142) or just its number (142).

Main endpoints

Endpoint What it does
GET /me Who the token belongs to
GET /projects Projects where you have an internal role
GET /projects/{project}/stages, /members, /labels A project’s stages, members and labels
GET /projects/{project}/tasks Tasks, with filters such as stage, assignee, label, priority, due_before and updated_since
POST /projects/{project}/tasks Create a task. Only title is required.
GET, PATCH, DELETE /projects/{project}/tasks/{task} Read, update or delete a task
POST /projects/{project}/tasks/{task}/move Move a task to another stage, if the workflow allows it
GET, POST /projects/{project}/tasks/{task}/comments Read and add comments
/projects/{project}/tasks/{task}/checklist Read and change the checklist

Lists use cursor pagination: set per_page (up to 100) and follow links.next until it’s null. Errors always have the same shape: {"error": {"code": "…", "message": "…", "details": {…}}}.

Webhooks

Project admins add webhooks in the project under Tools → Webhooks. Each one has its own signing secret, shown once when you add it.

  • Events: task.created, task.updated, task.moved, task.commented, task.published and task.deleted. Send test sends webhook.test.
  • Signature: each request has an X-Taskshire-Signature: t=…,v1=… header. v1 is the hex HMAC-SHA256 of {t}.{raw body}, keyed with the signing secret. Compare in constant time and reject anything more than five minutes old.
  • Duplicates: use the X-Taskshire-Delivery header (the same as the body’s id) to ignore repeats.
  • Retries: any 2xx counts as delivered. Failures are retried up to 8 times over about an hour. After 20 failures in a row, the webhook is switched off and project admins are told.
  • Addresses: only public https:// addresses. Taskshire won’t call private networks or follow redirects.

The full reference

The complete reference, with every endpoint, filter, field and error code, plus signature examples in PHP, JavaScript and Python, is in the Taskshire developer docs (docs/api.md). Ask whoever runs your Taskshire if you need a copy.

← All guides