FOfocusbear
to-do

GET /to-do/search

Request

  • Base URL
    https://api.focusbear.io (the document declares no server; this is the origin it was published from)
  • Auth
    HTTP bearer

Query parameters

takenumber
scope'OWNED' | 'MINE'

OWNED (default) returns every to-do the caller owns, whoever it is assigned to. MINE returns the caller's own work: to-dos they own that are unassigned or assigned to themselves, plus native project to-dos a colleague owns and assigned to them in a project they still own or are an accepted member of. To-dos the caller owns but assigned to someone else are left out.

titlestring required

Response

List of matching tasks

assignee_idstring nullable

Id of the user this task is assigned to, or null when it is unassigned.

external_task_statusstring

Cached external task status label used by task list endpoints.

external_statusesobject

Available external statuses on the linked project, when the todo is synced.

top_scorenumber nullable

@brief Materialised priority score, written by application code. @details Mirrors the SQL expression that previously computed the "top score" inside ORDER BY on every page load. Persisting the value allows the planner to satisfy ORDER BY ... LIMIT with the (user_id, top_score DESC) index instead of a parallel sequential scan + in-memory sort. The score depends on the user's local "today", so it is refreshed daily by the off-thread top-score worker as well as on every write that touches due_date, outcome, or perspiration_level.

     PostgreSQL's `numeric` type round-trips through node-postgres
     as a string; the transformer below converts it to `number`
     on read so the application can treat it as a plain numeric
     value.
assigned_mcp_token_idstring

ID of the MCP agent token assigned to this task

attachment_countnumber

Number of files attached to this task. Present on list reads (GET /to-do, Day Plan, recent).

user_idstring
focus_typestring
synced_project_idstring
project_idstring
custom_status_idstring
titlestring required
detailsstring required
objectivestring required
external_task_idstring
external_task_metadataobject
due_datestring date-time nullable
eisenhower_quadrantnumber required
outcomenumber required
perspiration_levelnumber required
statusstring required
durationnumber
iconstring
current_external_status_idstring nullable

@brief Materialised external status identifier from the linked platform. @details Populated by the integration sync worker so list-view rendering no longer needs to decrypt/parse the external_task_metadata JSONB on the request path.

current_external_status_labelstring nullable

@brief Materialised external status label from the linked platform. @details See current_external_status_id. The label is exposed via the API as the human-readable status text.

planned_datestring nullable

@brief Day Plan pointer: the day this todo is planned for (YYYY-MM-DD). @details NULL means the todo is not in any Day Plan. A planned task is a pointer into to_do by date, not a copy; the Day Plan panel reads todos by planned_date and writes planning changes through PATCH /to-do/:id.

planned_block_keystring nullable

@brief Day Plan time-box assignment within the planned day. @details Opaque, never parsed by the backend. One of event:<id>, deepwork:<unix-epoch>, habit:<title>, or NULL when planned but not yet time-boxed onto a block. Encrypted at rest because the habit:<title> form can embed a habit name, matching title/ details. The column stays unbounded varchar (ciphertext is longer than plaintext); the DTO caps plaintext input at 256 chars.

planned_ordernumber nullable

@brief Manual ordering within the planned day (drag-to-reorder).

recurrence_rulestring nullable

@brief Recurrence: canonical RFC 5545 RRULE content line, e.g. RRULE:FREQ=WEEKLY;INTERVAL=2 for a fortnightly chore. @details NULL means the todo is a one-off and takes no recurrence code path, which is every todo that existed before this column. Set together with the other three recurrence_* columns (a DB CHECK enforces all-or-none). Validated and canonicalised through the same RFC 5545 subset the Day Plan's event series use.

recurrence_timezonestring nullable

@brief Recurrence: IANA zone the rule is evaluated in (keeps the local time of day across DST).

recurrence_dtstartstring date-time nullable

@brief Recurrence: the series DTSTART — the first occurrence's due date. @details Copied unchanged onto every occurrence so the next due date is always computed from the series anchor. Completing an occurrence late therefore does not shift the schedule.

recurrence_series_idstring nullable

@brief Recurrence: groups every occurrence of one repeating todo. @details Equal to the first occurrence's own id. Lets history be read per series and DELETE /to-do?scope=series remove the whole thing.

idstring
created_atstring
updated_atstring

Changes

No recorded changes to this operation across all 1 revision of this API.