Items API

The Items API allows you to create, retrieve, update, and delete items within your Statements of Work. Items can be either Requirements (for high-level organization) or Task Items (for specific, testable work).

The Item Object

Name
id
Type
string
Description
Unique identifier for the item.
Name
title
Type
string
Description
The title of the item.
Name
description
Type
string
Description
A detailed description of the item.
Name
type
Type
string
Description
Item type: requirement or task_item.
Name
sowId
Type
string
Description
ID of the Statement of Work this item belongs to.
Name
parentItemId
Type
string
Description
ID of the parent item (null for top-level items).
Name
orderIndex
Type
number
Description
Order position within its hierarchy level.
Name
status
Type
string
Description
Current status: pending, in_progress, completed, cancelled.
Name
createdAt
Type
timestamp
Description
Timestamp of when the item was created.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the item was last updated.
Name
createdByUserId
Type
string
Description
ID of the user who created the item.

GET/api/sow/{sowId}/items

List items for a SOW

This endpoint allows you to retrieve all items for a specific Statement of Work.

Path Parameters

Name
sowId
Type
string
Required
Description
The ID of the SOW to retrieve items for.

Query Parameters

Name
type
Type
string
Description
Filter by item type: requirement or task_item.
Name
parentId
Type
string
Description
Filter by parent item ID.

Response

Returns an array of item objects for the specified SOW.

cURL

curl https://api.tanda.app/api/sow/sow_123/items \
  -H "Authorization: Bearer {token}"

Response

[
  {
    "id": "item_123",
    "title": "User Management System",
    "description": "Complete user authentication and profile system",
    "type": "requirement",
    "sowId": "sow_123",
    "parentItemId": null,
    "orderIndex": 1,
    "status": "in_progress",
    "createdAt": "2025-05-25T12:00:00Z",
    "updatedAt": "2025-05-25T12:00:00Z"
  },
  {
    "id": "item_456",
    "title": "Implement user registration",
    "description": "Create registration form and API endpoint",
    "type": "task_item",
    "sowId": "sow_123",
    "parentItemId": "item_123",
    "orderIndex": 1,
    "status": "pending",
    "createdAt": "2025-05-25T12:30:00Z",
    "updatedAt": "2025-05-25T12:30:00Z"
  }
]

GET/api/items/{itemId}

Retrieve an item

This endpoint allows you to retrieve a single item by its ID.

Path Parameters

Name
itemId
Type
string
Required
Description
The ID of the item to retrieve.

Response

Returns the item object if found.

cURL

curl https://api.tanda.app/api/items/item_123 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "item_123",
  "title": "User Management System",
  "description": "Complete user authentication and profile system",
  "type": "requirement",
  "sowId": "sow_123",
  "parentItemId": null,
  "orderIndex": 1,
  "status": "in_progress",
  "createdAt": "2025-05-25T12:00:00Z",
  "updatedAt": "2025-05-25T12:00:00Z"
}

POST/api/sow/{sowId}/items

Create an item

This endpoint allows you to create a new item within a Statement of Work.

Path Parameters

Name
sowId
Type
string
Required
Description
The ID of the SOW to create the item in.

Request Body

Name
title
Type
string
Required
Description
The title of the item.
Name
description
Type
string
Description
A detailed description of the item.
Name
type
Type
string
Required
Description
Item type: requirement or task_item.
Name
parentItemId
Type
string
Description
ID of the parent item (optional).
Name
orderIndex
Type
number
Description
Order position (auto-calculated if not provided).

Response

Returns the created item object.

cURL

curl -X POST https://api.tanda.app/api/sow/sow_123/items \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Payment Processing",
    "description": "Complete payment system with Stripe integration",
    "type": "requirement"
  }'

Response

{
  "id": "item_789",
  "title": "Payment Processing",
  "description": "Complete payment system with Stripe integration",
  "type": "requirement",
  "sowId": "sow_123",
  "parentItemId": null,
  "orderIndex": 2,
  "status": "pending",
  "createdAt": "2025-05-25T13:00:00Z",
  "updatedAt": "2025-05-25T13:00:00Z"
}

PUT/api/items/{itemId}

Update an item

This endpoint allows you to update an existing item.

Path Parameters

Name
itemId
Type
string
Required
Description
The ID of the item to update.

Request Body

Name
title
Type
string
Description
Updated title.
Name
description
Type
string
Description
Updated description.
Name
status
Type
string
Description
Updated status: pending, in_progress, completed, cancelled.
Name
orderIndex
Type
number
Description
Updated order position.

Response

Returns the updated item object.

cURL

curl -X PUT https://api.tanda.app/api/items/item_123 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed"
  }'

Response

{
  "id": "item_123",
  "title": "User Management System",
  "description": "Complete user authentication and profile system",
  "type": "requirement",
  "sowId": "sow_123",
  "parentItemId": null,
  "orderIndex": 1,
  "status": "completed",
  "createdAt": "2025-05-25T12:00:00Z",
  "updatedAt": "2025-05-25T14:00:00Z"
}

DELETE/api/items/{itemId}

Delete an item

This endpoint allows you to delete an item. Note: Deleting a requirement will also delete all child items.

Path Parameters

Name
itemId
Type
string
Required
Description
The ID of the item to delete.

Response

Returns a success message if the item was deleted.

cURL

curl -X DELETE https://api.tanda.app/api/items/item_123 \
  -H "Authorization: Bearer {token}"

Response

{
  "message": "Item deleted successfully"
}

PUT/api/sow/{sowId}/items/reorder

Reorder items

This endpoint allows you to reorder items within a SOW by updating their order indices.

Path Parameters

Name
sowId
Type
string
Required
Description
The ID of the SOW containing the items.

Request Body

Name
items
Type
array
Required
Description
Array of objects with id and orderIndex properties.

Response

Returns a success message and the updated items.

cURL

curl -X PUT https://api.tanda.app/api/sow/sow_123/items/reorder \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"id": "item_456", "orderIndex": 1},
      {"id": "item_123", "orderIndex": 2}
    ]
  }'

Response

{
  "message": "Items reordered successfully",
  "items": [
    {
      "id": "item_456",
      "orderIndex": 1
    },
    {
      "id": "item_123", 
      "orderIndex": 2
    }
  ]
}

Type-Specific Behaviors

Requirements

Cannot have tests: Requirements organize work but don't have direct acceptance criteria
Status aggregation: Status calculated from child task items
Hierarchical containment: Can contain both requirements and task items

Task Items

Can have tests: Task items can have acceptance criteria and associated tests
Direct testing: Binary pass/fail status based on test results
Limited containment: Can only contain other task items (sub-tasks)

Hierarchy Validation

The API enforces logical hierarchy rules:

✅ Requirements can contain requirements and task items
✅ Task items can contain task items (sub-tasks)
❌ Task items cannot contain requirements
❌ Circular dependencies are prevented

Error Responses

The API uses standard HTTP status codes:

200 OK - Request succeeded
201 Created - Item created successfully
400 Bad Request - Invalid request or hierarchy violation
401 Unauthorized - Missing or invalid authentication
403 Forbidden - Insufficient permissions
404 Not Found - Item or SOW not found
500 Internal Server Error - Server error

Error responses include descriptive messages:

{
  "error": "Invalid hierarchy: task items cannot contain requirements"
}