# tidybird Agent API Reference (Public Integration Surface)

This file is the **public** API contract for external agents.

- Date: 2026-03-24
- Stability: `Stable for integrations`
- Scope: **only** `/api/v1/**`

## Base URL

- Local: `http://localhost:3000/api/v1`
- Production: `https://tidybird.exploraworks.com/api/v1`

## Authentication

Use an API key created in Account > API Access Tokens.
API keys require an expiration date (max 365 days from creation).

Headers (pick one):

- `Authorization: Bearer <api_key>`
- `x-api-key: <api_key>`

Available scopes:

- `plans:read`
- `plans:write`
- `inbox:read`
- `inbox:write`

## Common Error Shape

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body must be application/json",
    "details": null
  }
}
```

Common codes: `UNAUTHORIZED`, `FORBIDDEN`, `VALIDATION_ERROR`, `CONFLICT`, `NOT_FOUND`, `RATE_LIMITED`, `INTERNAL_SERVER_ERROR`.

## Rate Limits

- API endpoints are rate-limited per client/IP.
- On limit, API returns `429 RATE_LIMITED`.

## Endpoints

### `GET /inbox`

- Scope: `inbox:read`
- Query:
  - `countOnly=1` (optional): returns only `{ count }`
  - `limit` (optional, positive integer, default `40`)
- Response:
  - `{ count, items }` or `{ count }`

### `POST /inbox`

- Scope: `inbox:write`
- Body:
  - `description` (string, required)
  - `estimatedMinutes` (number, optional)
- Response: `201 { item, count }`

### `GET /plans/week?anchorDate=YYYY-MM-DD`

- Scope: `plans:read`
- Query:
  - `anchorDate` (optional ISO date; defaults to today)
- Response:
  - `anchorDate`
  - `plannerWeekMode` (`mon_fri` | `mon_sun`)
  - `weekStartDate`
  - `weekEndDate`
  - `days[]` (`date`, `status`, `taskCount`, `planId`)

### `GET /plans/:date/tasks`

- Scope: `plans:read`
- Path:
  - `:date` ISO date (`YYYY-MM-DD`)
- Response:
  - `date`
  - `plan` (`null` when day has no plan)
  - `tasks` (`[]` when day has no plan)

### `POST /plans/:date/tasks`

- Scope: `plans:write`
- Path:
  - `:date` ISO date (`YYYY-MM-DD`)
- Behavior:
  - Auto creates/loads draft daily plan if missing.
  - Adds one task to that day.
- Body (one of):
  - `taskTemplateId` (string)
  - `quickTaskDescription` (string)
- Optional:
  - `estimatedMinutes` (number, for quick tasks)
  - `assignedUserId` (string or `null`)
- Response: `201 { plan, task }`

### `DELETE /plans/:date/tasks/:taskId`

- Scope: `plans:write`
- Path:
  - `:date` ISO date (`YYYY-MM-DD`)
  - `:taskId` UUID
- Behavior:
  - Removes one task from a draft plan.
  - Normalizes remaining order.
- Response: `{ ok: true }`

## cURL Examples

```bash
# List inbox items
curl -s \
  -H "Authorization: Bearer $tidybird_API_KEY" \
  "https://tidybird.exploraworks.com/api/v1/inbox?limit=20"

# Create inbox item
curl -s -X POST \
  -H "Authorization: Bearer $tidybird_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Clean terrace table"}' \
  "https://tidybird.exploraworks.com/api/v1/inbox"

# Get week overview
curl -s \
  -H "Authorization: Bearer $tidybird_API_KEY" \
  "https://tidybird.exploraworks.com/api/v1/plans/week?anchorDate=2026-03-20"

# Add task to a day (from library template)
curl -s -X POST \
  -H "Authorization: Bearer $tidybird_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"taskTemplateId":"<template_uuid>"}' \
  "https://tidybird.exploraworks.com/api/v1/plans/2026-03-20/tasks"

# List tasks for a day
curl -s \
  -H "Authorization: Bearer $tidybird_API_KEY" \
  "https://tidybird.exploraworks.com/api/v1/plans/2026-03-20/tasks"

# Delete task from a day
curl -s -X DELETE \
  -H "Authorization: Bearer $tidybird_API_KEY" \
  "https://tidybird.exploraworks.com/api/v1/plans/2026-03-20/tasks/<task_uuid>"
```

## Not Included Here

Internal endpoints such as `/api/admin/**`, `/api/ops/**`, `/api/billing/**`, `/api/me`, `/api/security/**` are intentionally excluded from this public agent contract.