Skip to main content
PATCH
https://tickward.com/api/v1
/
projects
/
{project_id}
/
timers
/
{timer_id}
Update a timer
curl --request PATCH \
  --url https://tickward.com/api/v1/projects/{project_id}/timers/{timer_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
{
  "object": "timer",
  "id": "timer_123",
  "project_id": "project_123",
  "project_name": "Travel",
  "label": "Flight to Tokyo",
  "target_date": "2026-10-10T09:30:00.000Z",
  "effective_target_date": "2026-10-10T09:30:00.000Z",
  "timezone": "Asia/Tokyo",
  "created_at": "2026-06-07T12:00:00.000Z",
  "updated_at": "2026-06-07T12:00:00.000Z",
  "archived_at": null,
  "color": "#2563eb",
  "description": "Pack before leaving for the airport.",
  "space_id": "travel",
  "shared_at": null,
  "notify": true,
  "recurrence": null,
  "pinned": false,
  "image": null
}

Authorizations

​
Authorization
string
header
default:tw_your_api_key
required

Use a tickward API key from Settings. API keys start with tw_. Store keys as secrets and send them as Authorization: Bearer <key>.

Headers

​
Idempotency-Key
string

Optional for POST, PATCH, and DELETE requests. Generate a random UUID with an operation prefix, for example timer-create-${crypto.randomUUID()}. Reuse the same key with the same method, path, query, and JSON body to safely retry one logical write for up to 24 hours. Reusing it with a different request returns 409. The server stores only a hash of the key.

Required string length: 8 - 128
Pattern: ^[A-Za-z0-9._:-]+$

Path Parameters

​
project_id
string
required
​
timer_id
string
required

Body

application/json
​
label
string
Required string length: 1 - 200
​
target_date
string<date-time>

ISO 8601 datetime string. Prefer UTC with Z or an explicit offset.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}
Example:

"2026-10-10T09:30:00.000Z"

​
timezone
string

IANA timezone name, for example Europe/Warsaw or America/New_York.

Example:

"Europe/Warsaw"

​
archived_at
string<date-time> | null
Example:

"2026-10-10T09:30:00.000Z"

​
color
string | null
Pattern: ^$|^#[0-9a-fA-F]{6}$
​
description
string
Maximum string length: 200
​
space_id
string | null
Required string length: 1 - 64
​
notify
boolean
​
recurrence
object
​
pinned
boolean
​
image
object

Response

Timer.

​
object
string
required
Allowed value: "timer"
​
id
string
required
​
project_id
string
required
​
project_name
string
required

Human-readable project name. Agents should prefer this over project_id in user-facing confirmations.

​
label
string
required
Maximum string length: 200
​
target_date
string<date-time>
required

Original timer target date. For recurring timers this is the schedule anchor, not necessarily the current countdown date.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}
Example:

"2026-10-10T09:30:00.000Z"

​
effective_target_date
string<date-time>
required

Current countdown date. For one-off timers this equals target_date. For recurring timers this is the next occurrence after the current server time.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}
Example:

"2026-10-10T09:30:00.000Z"

​
timezone
string
required

IANA timezone name, for example Europe/Warsaw or America/New_York.

Example:

"Europe/Warsaw"

​
created_at
string<date-time>
required

ISO 8601 datetime string. Prefer UTC with Z or an explicit offset.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}
Example:

"2026-10-10T09:30:00.000Z"

​
updated_at
string<date-time>
required

ISO 8601 datetime string. Prefer UTC with Z or an explicit offset.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}
Example:

"2026-10-10T09:30:00.000Z"

​
archived_at
string<date-time> | null
required
Example:

"2026-10-10T09:30:00.000Z"

​
color
string | null
required
Pattern: ^#[0-9a-fA-F]{6}$
​
description
string | null
required
Maximum string length: 200
​
space_id
string | null
required
​
shared_at
string<date-time> | null
required
Example:

"2026-10-10T09:30:00.000Z"

​
notify
boolean
required
​
recurrence
object
required
​
pinned
boolean
required
​
image
object
required