Skip to main content

Kanban Cards

Manage custom cards on Kanban boards. List, retrieve, create, update, and move cards between columns.

Prerequisites

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

List Cards​

Retrieve a paginated list of cards for a specific board.

GET/apidev/v1/kanban/boards/{id}/cards
PermissionAPICLI_KANBAN_READ
Rate Limit30 req/min (sliding window)
Cache15s

Request Headers​

Every request to a protected endpoint requires these headers:

HeaderRequiredDescription
AuthorizationYesBearer token obtained from the Login endpoint. Format: Bearer <token>
X-API-KeyYesCompany integration key provided during onboarding. Format: gtk_xxx...
tenantYesYour company hostname (e.g., yourcompany.geotareas.com)
Content-TypeConditionalapplication/json — required for POST and PUT requests

Path Parameters​

ParameterTypeRequiredDescription
idstringYesBoard unique identifier (BigInt)

Query Parameters​

ParameterTypeRequiredDefaultConstraintsDescription
limitintegerNo100Min 1, Max 100Records per page
offsetintegerNo0≥ 0Records to skip
column_idstringNo—Max length 30Filter by column ID (BigInt)
prioritystringNo—NONE, LOW, MEDIUM, HIGH, URGENTFilter by priority
assignee_idstringNo—Max length 30Filter by assignee ID (BigInt)
searchstringNo—Max length 120Search card title
archivedbooleanNofalse—Include archived cards

Response​

FieldTypeDescription
idstringCard unique identifier (BigInt)
board_idstringParent board ID (BigInt)
column_idstringCurrent column ID (BigInt)
column_namestringCurrent column name
titlestringCard title
descriptionstring | nullCard description
prioritystringPriority level
colorstring | nullCard color hex code
due_datestring | nullDue date (ISO 8601)
labelsarrayLabel objects with name and color
checklist_totalintegerTotal checklist items
checklist_completedintegerCompleted checklist items
assigneeobject | null{id, name} of the assignee
comments_countintegerNumber of comments
orderintegerPosition within the column
archivedbooleanWhether the card is archived
created_atstringISO 8601 timestamp
updated_atstringISO 8601 timestamp

Code Examples​

curl -s -X GET "$TENANT_URL/apidev/v1/kanban/boards/8391728491728491/cards?limit=20&priority=HIGH" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

Example Response​

{
  "success": true,
  "data": [
    {
      "id": "4200000000000001",
      "board_id": "8391728491728491",
      "column_id": "9100000000000002",
      "column_name": "In Progress",
      "title": "Review Q1 fleet maintenance schedule",
      "description": "Verify all units have scheduled maintenance before April.",
      "priority": "HIGH",
      "color": "#EF4444",
      "due_date": "2026-03-25T18:00:00",
      "labels": [{"name": "maintenance", "color": "#F59E0B"}],
      "checklist_total": 5,
      "checklist_completed": 3,
      "assignee": {"id": "1100000000000001", "name": "Carlos Mendoza"},
      "comments_count": 3,
      "order": 1,
      "archived": false,
      "created_at": "2026-03-10T09:00:00",
      "updated_at": "2026-03-18T14:30:00"
    }
  ],
  "meta": {
    "total": 8,
    "limit": 20,
    "offset": 0
  }
}

Rate Limit Headers​

Every response includes rate limit information in the headers:

HeaderDescription
X-RateLimit-LimitMaximum number of requests allowed in the current window
X-RateLimit-RemainingNumber of requests remaining in the current window
X-RateLimit-ResetUnix timestamp (seconds) when the current window resets
Retry-AfterSeconds to wait before retrying (only present on 429 responses)
X-Request-IdUnique request identifier for debugging and support tickets

Card Detail​

Retrieve the full details for a single card, including checklist items and custom fields.

GET/apidev/v1/kanban/cards/{id}
PermissionAPICLI_KANBAN_READ
Rate Limit30 req/min (sliding window)
Cache15s

Path Parameters​

ParameterTypeRequiredDescription
idstringYesCard unique identifier (BigInt)

Response​

Returns all fields from the List endpoint, plus:

FieldTypeDescription
checklistarray[{text, checked}] checklist items
custom_fieldsarray[{field_id, name, type, value}] custom field values
created_byobject{id, name} of the creator

Code Examples​

curl -s -X GET "$TENANT_URL/apidev/v1/kanban/cards/4200000000000001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

Example Response​

{
  "success": true,
  "data": {
    "id": "4200000000000001",
    "board_id": "8391728491728491",
    "column_id": "9100000000000002",
    "column_name": "In Progress",
    "title": "Review Q1 fleet maintenance schedule",
    "description": "Verify all units have scheduled maintenance before April.",
    "priority": "HIGH",
    "color": "#EF4444",
    "due_date": "2026-03-25T18:00:00",
    "labels": [{"name": "maintenance", "color": "#F59E0B"}],
    "checklist": [
      {"text": "Check unit 01 schedule", "checked": true},
      {"text": "Check unit 02 schedule", "checked": true},
      {"text": "Check unit 03 schedule", "checked": true},
      {"text": "Order replacement parts", "checked": false},
      {"text": "Confirm technician availability", "checked": false}
    ],
    "assignee": {"id": "1100000000000001", "name": "Carlos Mendoza"},
    "custom_fields": [
      {"field_id": "6200000000000001", "name": "Region", "type": "select", "value": "North"}
    ],
    "comments_count": 3,
    "created_by": {"id": "1100000000000002", "name": "Admin User"},
    "created_at": "2026-03-10T09:00:00",
    "updated_at": "2026-03-18T14:30:00",
    "archived": false
  },
  "meta": {}
}

Create Card​

Create a new card on a board. Returns HTTP 201.

POST/apidev/v1/kanban/cards
PermissionAPICLI_KANBAN_WRITE
Rate Limit10 req/min (sliding window)

Request Body​

FieldTypeRequiredConstraintsDescription
board_idstringYesMax length 30Target board ID (BigInt)
column_idstringYesMax length 30Target column ID (BigInt)
titlestringYesMax length 500Card title
descriptionstringNoMax length 5000Card description
prioritystringNoMax length 10NONE, LOW, MEDIUM, HIGH, URGENT
colorstringNoMax length 10Hex color code
due_datestringNoMax length 30ISO 8601 date
labelsarrayNo—[{name (required, max 50), color (max 10)}]
checklistarrayNo—[{text (required, max 500), checked (boolean)}]
assignee_idstringNoMax length 30Assignee user ID (BigInt)
custom_fieldsarrayNo—[{field_id (required, max 30), value (max 500)}]

Response​

FieldTypeDescription
idstringCreated card ID (BigInt)
board_idstringBoard ID (BigInt)
column_idstringColumn ID (BigInt)
titlestringCard title

Code Examples​

curl -s -X POST "$TENANT_URL/apidev/v1/kanban/cards" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "board_id": "8391728491728491",
    "column_id": "9100000000000001",
    "title": "Schedule maintenance for unit #12",
    "priority": "MEDIUM",
    "labels": [{"name": "maintenance", "color": "#F59E0B"}],
    "checklist": [{"text": "Confirm schedule", "checked": false}],
    "due_date": "2026-04-01T12:00:00"
  }'

Example Response​

{
  "success": true,
  "data": {
    "id": "4200000000000002",
    "board_id": "8391728491728491",
    "column_id": "9100000000000001",
    "title": "Schedule maintenance for unit #12"
  },
  "meta": {}
}

Update Card​

Update an existing card. Only provided fields are modified (partial update).

PUT/apidev/v1/kanban/cards/{id}
PermissionAPICLI_KANBAN_WRITE
Rate Limit10 req/min (sliding window)

Path Parameters​

ParameterTypeRequiredDescription
idstringYesCard unique identifier (BigInt)

Request Body​

Same fields as Create Card. All fields are optional.

Response​

FieldTypeDescription
idstringCard ID (BigInt)
updated_fieldsstring[]List of fields that were modified

Code Examples​

curl -s -X PUT "$TENANT_URL/apidev/v1/kanban/cards/4200000000000001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": "URGENT",
    "assignee_id": "1100000000000003"
  }'

Example Response​

{
  "success": true,
  "data": {
    "id": "4200000000000001",
    "updated_fields": ["priority", "assignee_id"]
  },
  "meta": {}
}

Move Card​

Move a card to a different column and/or change its position.

PUT/apidev/v1/kanban/cards/{id}/move
PermissionAPICLI_KANBAN_WRITE
Rate Limit10 req/min (sliding window)

Path Parameters​

ParameterTypeRequiredDescription
idstringYesCard unique identifier (BigInt)

Request Body​

FieldTypeRequiredConstraintsDescription
target_column_idstringYesMax length 30Destination column ID (BigInt)
positionintegerNo≥ 0Target position within the column. Default: appended at end

Response​

FieldTypeDescription
idstringCard ID (BigInt)
previous_column_idstringPrevious column ID (BigInt)
new_column_idstringNew column ID (BigInt)
positionintegerNew position within the column

Code Examples​

curl -s -X PUT "$TENANT_URL/apidev/v1/kanban/cards/4200000000000001/move" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "target_column_id": "9100000000000003",
    "position": 0
  }'

Example Response​

{
  "success": true,
  "data": {
    "id": "4200000000000001",
    "previous_column_id": "9100000000000002",
    "new_column_id": "9100000000000003",
    "position": 0
  },
  "meta": {}
}

Errors​

CodeHTTPDescription
BAD_REQUEST400Missing required headers
VALIDATION_ERROR400Invalid parameters
UNAUTHORIZED401Invalid or expired JWT / API Key
FORBIDDEN403User lacks required permission
NOT_FOUND404Resource not found
RATE_LIMITED429Exceeded rate limit
INTERNAL_ERROR500Unexpected server error