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 company hostname (e.g., yourcompany.geotareas.com)
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: SA, ASI, ACE, INI, USU, FIN, CAN
driver_id	string	No	Max length 30	Driver to assign (BigInt). Required for ASI transition

Response

Field	Type	Description
task_id	string	Task unique identifier (BigInt)
previous_status	string	Status before the transition
new_status	string	Status after the transition
updated_at	string	ISO 8601 timestamp

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
BAD_REQUEST	400	Missing required headers
VALIDATION_ERROR	400	Invalid parameters
STATE_CHANGE_FAILED	400	Invalid state transition (e.g. FIN to SA)
UNAUTHORIZED	401	Invalid or expired JWT / 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