API Reference

GET /api/tasks

List inbox tasks — untriaged (Triage Status = "New"), not archived — scoped to the authenticated user.

Example

curl -H "X-API-Key: your-key" https://tasks.xray.tech/api/tasks

Response

{
  "tasks": [
    {
      "id": "recXXXXXXXXXXXXXX",
      "title": "Update onboarding docs",
      "description": "The onboarding guide needs updating for new hires",
      "status": "Ready to Start",
      "priority": "P2: Medium Priority",
      "triageStatus": "New",
      "origin": "Human",
      "originDetail": "Mark via Slack",
      "triageNotes": "",
      "assignedTo": { "id": "usr...", "email": "mark@xray.tech", "name": "Mark Campos" },
      "requestedBy": null,
      "assignedToAI": "mark@xray.tech",
      "project": [],
      "projectName": "",
      "dueDate": null,
      "startDate": null,
      "hoursEstimated": null,
      "hoursUsed": null,
      "isArchived": false,
      "linkToTaskInterface": "https://airtable.com/...",
      "createdAt": "2026-03-10T14:30:00.000Z"
    }
  ]
}

GET /api/tasks/mine

The user's active board: every task assigned to them that is not Done, Cancelled, Rejected, or archived. Tasks completed more than 30 days ago are excluded.

curl -H "X-API-Key: your-key" https://tasks.xray.tech/api/tasks/mine

GET /api/tasks/sent

Tasks the authenticated user requested for other people.

GET /api/tasks/search

Search tasks with server-side filters.

Parameters

GET /api/tasks/history

Recently resolved tasks for the current user. Optional ?days=30 (default 30).

GET /api/tasks/:id

Get a single task by its Airtable record ID.

{ "task": { "id": "recXXXXXXXXXXXXXX", "title": "...", ... } }

POST /api/tasks

Create a new inbox task. Sets Status = "Ready to Start" and Triage Status = "New" automatically.

Request Body

Example

curl -X POST \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Update client proposal",
    "description": "Revise the SOW section with new pricing",
    "origin": "AI Agent",
    "originDetail": "Claude Code",
    "priority": "P1: Top Priority",
    "assignedTo": "mark@xray.tech"
  }' \
  https://tasks.xray.tech/api/tasks

Response (201 Created)

{ "ok": true, "task": { "id": "recNEW...", "title": "Update client proposal", ... } }

PATCH /api/tasks/:id

Partial update — only include fields you want to change. Send null to clear a clearable field (e.g. {"dueDate": null}).

Updatable Fields

Example — Mark as done

curl -X PATCH \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"status": "Done", "triageStatus": "Accepted"}' \
  https://tasks.xray.tech/api/tasks/recXXXXXXXXXXXXXX

POST /api/tasks/:id/accept

Accept a task and link it to a project. Optionally sets an initial status (default "Ready to Start").

Request Body

POST /api/tasks/:id/reject

Reject a task with a reason.

{ "reason": "Duplicate of existing task" }

POST /api/tasks/:id/needs-info

Request more information before triaging.

{ "note": "Which client is this for?" }

POST /api/tasks/:id/archive

Archive a task. No request body. Archived tasks disappear from all list views but remain in Airtable (reversible there).

POST /api/tasks/:id/delegate

Reassign a task, notifying the new assignee and recording the handoff in triage notes.

Request Body

POST /api/tasks/:id/shortlink

Generate and save a Kutt shortlink for the task. No request body.

POST /api/tasks/bulk

Apply one action to many tasks at once.

Request Body

Response

{ "ok": true, "successful": ["rec...", "rec..."], "failedCount": 0 }

GET /api/proposals

List open proposals (aiStatus = "To Consider") for the authenticated user, enriched with target task, meeting, and project context. Proposals whose linked task is already Done, Cancelled, or archived are skipped.

{
  "proposals": [
    {
      "id": "recPROPOSAL123",
      "name": "[NEW Task] Confirm renewal with client",
      "type": "Status Update",
      "aiStatus": "To Consider",
      "proposedChangesObj": { "action": "create_task", ... },
      "taskTitle": "...",          // when targeting an existing task
      "meetingData": { "title": "...", "date": "...", "url": "...", "authorName": "..." },
      "projectData": { "id": "recPROJECT123", "name": "...", "clientId": "..." }
    }
  ]
}

POST /api/proposals

Create a proposal targeting a task, project, or outcome. Requires at least one of taskId, projectId, outcomeId, plus type and a payload describing the change (actions include change_status, change_priority, reassign, change_due_date, change_description, and more).

POST /api/proposals/:id/accept

Accept a proposal — the server applies the proposed change. Only the proposal's owner can accept, and only while it is still "To Consider".

POST /api/proposals/:id/reject

Reject (dismiss) a proposal. Same ownership and state rules as accept.

{ "reason": "Duplicate suggestion from the same meeting" }

GET /api/projects?q=search

Search projects by name (min 2 characters). Returns up to 10 matches.

{ "projects": [{ "id": "recPROJECT123", "name": "Client Onboarding v2" }] }

GET /api/projects/mine

Projects managed by the current user.

GET /api/projects/:id

Combined context for one project: the project record plus its active tasks, completed tasks, and recent meetings.

{ "project": {...}, "activeTasks": [...], "completedTasks": [...], "meetings": [...] }

PATCH /api/projects/:id

Update project fields: status, priority, startDate, endDate, clientId, accountManager.

GET /api/clients

List all clients.

{ "clients": [{ "id": "recCLIENT123", "name": "ACME Corp" }] }

GET /api/clients/search?q=

Search clients by name. Empty query returns an empty list.

GET /api/outcomes?projectId=rec...

List outcomes for a project. projectId is required.

GET /api/meetings/recent

Fetch recent meetings. By default, returns meetings you attended or created.

Parameters

Response

{
  "meetings": [
    {
      "id": "recMEETING123",
      "name": "Weekly Sync with ACME",
      "startTime": "2026-03-25T10:00:00.000Z",
      "duration": 3600,
      "link": { "label": "View Transcript", "url": "https://..." },
      "recordingType": "shared_screen_with_speaker_view",
      "transcriptUrl": "https://...",
      "projects": ["ACME Q1 Deliverables"],
      "clients": ["ACME Corp"],
      "users": "mark@xray.tech",
      "summary": "Discussed the new onboarding flow.",
      "keyProgress": "Frontend components are complete.",
      "decisionsMade": "We will use Bolt.js for the Slack app.",
      "nextActions": "- Mark to finalize the API docs.",
      "actionable": "# Raw Action Items Markdown..."
    }
  ]
}

Note: the timestamp key is startTime, and projects/clients contain name strings, not record IDs.

GET /api/meetings/pending

Meetings awaiting deep-match processing.

GET /api/settings

The user's display and notification preferences.

PATCH /api/settings

Update preferences: showSentNav (display), notifications.channel / notifications.frequency.

GET /health

Health check (no auth required).

{ "status": "ok", "timestamp": "2026-03-10T15:00:00.000Z" }