Kanban Task State

Transition tasks through workflow states on a Kanban board. External systems can move tasks between statuses directly from the kanban context.

Prerequisites

All endpoints on this page require a valid JWT token, API key, and tenant header. See Authentication for details.

---

Update Task State

Transition a task to a new workflow state.

PUT/apidev/v1/kanban/tasks/{taskId}/state

PermissionAPICLI_KANBAN_WRITE

Rate Limit10 req/min (sliding window)

Request Headers

Every request to a protected endpoint requires these headers:

Header	Required	Description
Authorization	Yes	Bearer token obtained from the Login endpoint. Format: Bearer <token>
X-API-Key	Yes	Company integration key provided during onboarding. Format: gtk_xxx...
tenant	Yes	Your assigned tenant domain (default: geotareas.com) — always send your assigned tenant
Content-Type	Conditional	application/json — required for POST and PUT requests

Path Parameters

Parameter	Type	Required	Description
taskId	string	Yes	Task unique identifier (BigInt)

Request Body

Field	Type	Required	Constraints	Description
board_id	string	Yes	Max length 30	Board the task belongs to (BigInt)
target_status	string	Yes	Max length 10	Target status: ACE, INI, USU, FIN, CAN
driver_id	string	No	Max length 30	Driver to assign (BigInt)

Response

Field	Type	Description
task_id	string	Task unique identifier (BigInt)
previous_status	string | null	Status the task was in before the transition. Read just before the change; null on the rare occasion it could not be read
new_status	string	Status after the transition
updated_at	string	ISO 8601 timestamp

previous_status is populated

The status is captured immediately before the transition is applied, so you get the real prior value — useful for building an audit trail without a separate read. Treat null as "unknown", not as "no previous status": the transition itself still succeeded.

Code Examples

cURL

curl -s -X PUT "$TENANT_URL/apidev/v1/kanban/tasks/5001847291847291/state" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "board_id": "8391728491728491",
    "target_status": "FIN"
  }'

JavaScript

const response = await fetch(
  `${TENANT_URL}/apidev/v1/kanban/tasks/5001847291847291/state`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "X-API-Key": APIKEY,
      "tenant": TENANT,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      board_id: "8391728491728491",
      target_status: "FIN",
    }),
  }
);

const { data } = await response.json();
console.log(`Task ${data.task_id}: ${data.previous_status} -> ${data.new_status}`);

Python

import requests

response = requests.put(
    f"{TENANT_URL}/apidev/v1/kanban/tasks/5001847291847291/state",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "X-API-Key": APIKEY,
        "tenant": TENANT,
    },
    json={
        "board_id": "8391728491728491",
        "target_status": "FIN",
    },
)

task = response.json()["data"]
print(f"Task {task['task_id']}: {task['previous_status']} -> {task['new_status']}")

Example Response

{
  "success": true,
  "data": {
    "task_id": "5001847291847291",
    "previous_status": "INI",
    "new_status": "FIN",
    "updated_at": "2026-03-19T16:45:00"
  },
  "meta": {}
}

Rate Limit Headers

Every response includes rate limit information in the headers:

Header	Description
X-RateLimit-Limit	Maximum number of requests allowed in the current window
X-RateLimit-Remaining	Number of requests remaining in the current window
X-RateLimit-Reset	Unix timestamp (seconds) when the current window resets
Retry-After	Seconds to wait before retrying (only present on 429 responses)
X-Request-Id	Unique request identifier for debugging and support tickets

---

Errors

Code	HTTP	Description
VALIDATION_ERROR	400	Invalid parameters
STATE_CHANGE_FAILED	400	Invalid state transition (e.g. FIN to SA)
UNAUTHORIZED	401	Missing, invalid, or expired tenant / Authorization / X-API-Key
FORBIDDEN	403	User lacks required permission
NOT_FOUND	404	Resource not found
RATE_LIMITED	429	Exceeded rate limit
INTERNAL_ERROR	500	Unexpected server error