API Documentation

Authentication

The API uses Bearer token authentication. You can create personal API tokens from your profile settings.

Creating an API Token

Go to your Profile Settings
Scroll to "Personal API Tokens"
Click "Create Token" and give it a descriptive name
Copy the token immediately — you won't be able to see it again

Using Your Token

Include your token in the Authorization header:

http

Authorization: Bearer YOUR_API_TOKEN

Example Request

bash

curl -X GET "https://thisweek.is/api/workspaces" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Keep Your Token Secret

Treat your API token like a password. Don't share it or commit it to version control. If a token is compromised, revoke it immediately from your profile settings.

Quick Start Guide

Follow these steps to create your first task via the API:

Step 1: Get Your Workspace ID

bash

curl -X GET "https://thisweek.is/api/workspaces" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Step 2: Get Spaces in the Workspace

bash

curl -X GET "https://thisweek.is/api/workspaces/1/spaces" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Step 3: Get Projects in a Space

bash

curl -X GET "https://thisweek.is/api/workspaces/1/spaces/1/projects" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Step 4: Create a Task

bash

curl -X POST "https://thisweek.is/api/workspaces/1/spaces/1/projects/1/tasks" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task": {
      "title": "My first API task",
      "description": "Created via the API",
      "status": "not_started",
      "priority": 2
    }
  }'

Workspaces

Workspaces are the top-level containers for organizing your work.

GET

/api/workspaces

List all workspaces you have access to

Response

json
{
  "workspaces": [
    {
      "id": 1,
      "name": "Main Workspace",
      "description": null,
      "status": "active",
      "spaces": []
    }
  ]
}

Spaces

Spaces are containers within workspaces for related projects and tasks.

GET

/api/workspaces/:workspace_id/spaces

List all spaces in a workspace

Response

json
{
  "spaces": [
    {
      "id": 1,
      "name": "Product Development",
      "description": "Main product work",
      "status": "active",
      "workspace_id": 1,
      "board_name": "Tasks"
    }
  ]
}

Projects

Projects group related tasks within a space.

Project object

Every project response includes:

id, name, description, color, position, space_id
task_count — total tasks
completion_percentage — % of tasks done
task_counts_by_status — object of status key → count
all_tasks_done — true if all tasks are done

GET

/api/workspaces/:workspace_id/spaces/:space_id/projects

List all projects in a space

POST

/api/workspaces/:workspace_id/spaces/:space_id/projects

Create a new project

Request Body

json
{
  "project": {
    "name": "Q1 Goals",
    "description": "First quarter objectives",
    "color": "#3B82F6",
    "position": 0
  }
}

PATCH

/api/workspaces/:workspace_id/spaces/:space_id/projects/:id

Update a project

DELETE

/api/workspaces/:workspace_id/spaces/:space_id/projects/:id

Delete a project and all its tasks

Tasks

Tasks are the core work items in ThisWeek.

Task object

Every task response includes core and computed fields:

Core: id, title, description, status, priority, due_date, position, project_id, space_id, custom_fields
Assignees: assignees — array of { id, email, name, avatar }
Display: status_display, priority_display, project_name, project_color, due_date_formatted
State: overdue, due_today, completed, in_progress, blocked, archived, trashed
Timestamps: created_at, updated_at (ISO 8601)

Task Statuses

not_started

Not Started

working_on_it

Working on it

stuck

Stuck

done

Done

Priority Levels

0

None

1

Low

2

Medium

3

High

GET

/api/workspaces/:workspace_id/spaces/:space_id/tasks

List all tasks in a space

Query Parameters

status — Filter by status
priority — Filter by priority level
project_id — Filter by project

POST

/api/.../projects/:project_id/tasks

Create a new task

Request Body

json
{
  "task": {
    "title": "Implement new feature",
    "description": "Add the checkout flow",
    "status": "not_started",
    "priority": 2,
    "due_date": "2025-02-15"
  }
}

PATCH

/api/.../tasks/:id

Update a task

PATCH

/api/.../tasks/:id/move_to_project

Move a task to a different project

Request Body

json
{ "target_project_id": 5 }

PATCH

/api/.../tasks/:id/toggle_status

Toggle task between done and not_started

DELETE

/api/.../tasks/:id

Move task to trash (recoverable for 30 days)

Assignees

Tasks can have multiple assignees. Each item has id, email, name, and avatar.

GET

/api/.../tasks/assignable_users

List users who can be assigned (owner + accepted collaborators)

POST

/api/.../tasks/:id/assign_user

Assign a user. Body: { "user_id": 123 }

DELETE

/api/.../tasks/:id/unassign_user?user_id=123

Unassign a user from the task

Custom Fields

Track numeric values on tasks such as sale amounts, hours, or percentages. Define field types at the space level, then set values on individual tasks.

Field Types

number

Plain number

currency

e.g. £250.00

hours

e.g. 8 hrs

percentage

e.g. 75%

Field Definitions

Field definitions are created at the space level and apply to all tasks within that space.

GET

/api/.../task_custom_field_definitions

List all custom field definitions for a space

Response

json
{
  "field_definitions": [
    {
      "id": 1,
      "name": "Sale Amount",
      "field_type": "currency",
      "prefix": "£",
      "suffix": "",
      "show_sum": true,
      "position": 0
    }
  ]
}

POST

/api/.../task_custom_field_definitions

Create a new custom field definition

Request Body

json
{
  "field_definition": {
    "name": "Sale Amount",
    "field_type": "currency",
    "prefix": "£",
    "suffix": "",
    "show_sum": true
  }
}

GET

/api/.../task_custom_field_definitions/:id

Get a single custom field definition

PATCH

/api/.../task_custom_field_definitions/:id

Update a custom field definition

DELETE

/api/.../task_custom_field_definitions/:id

Delete a custom field definition (removes all values from tasks)

POST

/api/.../task_custom_field_definitions/reorder

Reorder custom field definitions

Request Body

json
{ "field_ids": [3, 1, 2] }

Setting Custom Field Values on Tasks

Include the custom_fields object with field definition IDs as keys.

json
{
  "task": {
    "title": "Close enterprise deal",
    "custom_fields": {
      "1": { "value": 25000.00, "label": "Sale Amount", "prefix": "£" },
      "2": { "value": 40, "label": "Hours Estimated", "suffix": " hrs" }
    }
  }
}

Custom Fields in Responses

When retrieving tasks, the custom_fields object is included with current values for each defined field.

Clearing Values

Set a field to null to clear it: "custom_fields": { "1": null }

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

Code	Meaning
200	Success
201	Created successfully
401	Unauthorized — Invalid or missing token
403	Forbidden — No permission to access this resource
404	Not found — Resource doesn't exist or no access
422	Validation error — Check the error message for details
500	Server error — Please try again or contact support

Error Response Format

json
{
  "error": "Workspace not found"
}

// Validation errors:
{
  "errors": {
    "title": ["can't be blank"],
    "status": ["is not a valid status"]
  }
}

API Documentation

Authentication

Creating an API Token

Using Your Token

Example Request

Keep Your Token Secret

Quick Start Guide

Step 1: Get Your Workspace ID

Step 2: Get Spaces in the Workspace

Step 3: Get Projects in a Space

Step 4: Create a Task

Workspaces

Response

Spaces

Response

Projects

Project object

Request Body

Tasks

Task object

Task Statuses

Priority Levels

Query Parameters

Request Body

Request Body

Assignees

Custom Fields

Field Types

Field Definitions

Response

Request Body

Request Body

Setting Custom Field Values on Tasks

Custom Fields in Responses

Clearing Values

Error Handling

Error Response Format

Ready to get started?