Agent API

Every operation is one HTTP call. These are the same operations your AI uses over MCP and the CLI runs, so anything one can do, the others can too.

Requests

Send POST https://kriyan.app/api/v1/<operation> with a JSON object as the body and a personal access token from Settings in the Authorization header. GET https://kriyan.app/api/v1 lists every operation with its JSON Schema.

Read today

curl -X POST https://kriyan.app/api/v1/get_today \
  -H "Authorization: Bearer $KRIYAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Add a task from a sentence

curl -X POST https://kriyan.app/api/v1/add_task \
  -H "Authorization: Bearer $KRIYAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "essay fri 5pm #school every week remind 1h before"}'

Responses

A call that worked answers 200 with { "result": ... }. Anything else answers with { "error": "..." }, written to be shown to a person or fixed by an agent:

400: the body isn't valid, or Kriyan refused the change. The message names the field.
401: no token, or the token was revoked.
404: there's no operation with that name.
500: something failed on Kriyan's side. Try again.

Dates are dates in your own calendar, like 2026-10-13, and “today” is today in the time zone from your profile. Times are minutes after midnight: 14:30 is 870. Lengths are minutes, and are only set when you know them.

Operations

get_today: Get today
get_week: Get a week
get_inbox: Get the inbox
get_space: Get a space
list_spaces: List spaces
get_progress: Get progress
add_task: Add a task
update_task: Change a task
complete_task: Complete a task
reopen_task: Reopen a task
delete_task: Delete a task
move_tasks: Move tasks
add_space: Add a space
update_space: Change a space
add_habit: Add a habit
check_habit: Check a habit
add_goal: Add a goal
update_goal: Change a goal
propose_plan: Propose a plan

`get_today`

Get today. Reads only, never changes anything.

Read the person's plan for a day (today by default): scheduled blocks, anytime tasks, done tasks, tasks left from earlier days, and habits. Read this before planning.

Field	Type	About
`date`	string	A date like 2026-10-13, in the person's own calendar.

`get_week`

Get a week. Reads only, never changes anything.

Read seven days starting on a date (Monday of this week by default): each day's blocks, deadlines and planned hours against capacity, plus the inbox and unscheduled tasks.

Field	Type	About
`start`	string	A date like 2026-10-13, in the person's own calendar.

`get_inbox`

Get the inbox. Reads only, never changes anything.

Read tasks captured without a date or a space.

Send an empty object.

`get_space`

Get a space. Reads only, never changes anything.

Read one space: its next and later tasks, child spaces, goals, note and stats.

Field	Type	About
`spaceId` (required)	string	The space's id.

`list_spaces`

List spaces. Reads only, never changes anything.

List every space as a tree, with ids, colours and paths like 'Work / Kriyan'.

Send an empty object.

`get_progress`

Get progress. Reads only, never changes anything.

Read time done this week and this year, time by space, goals against pace and habits.

Send an empty object.

`add_task`

Add a task. Changes your plan.

Add a task. Either pass `text` as one sentence the way a person types it ('essay fri 5pm #school every week remind 1h before') or pass the fields. Only the title is required. Never invent a length.

Field	Type	About
`text`	string	One sentence, parsed like the app's quick add.
`title`	string
`spaceId`	string	The space's id.
`date`	string	A date like 2026-10-13, in the person's own calendar.
`time`	integer, 0 to 1439	Start time, in minutes after midnight (14:30 is 870).
`length`	integer, 1 to 1440	Length in minutes. Leave it out unless the person said how long; never guess.
`deadline`	string	When it's due, if different from the day it's planned for.
`repeat`	object	How the task repeats. Examples: every Tue and Thu {freq:'week',interval:1,weekdays:[1,3]}; last day of each month {freq:'month',interval:1,monthly:{kind:'last'}}; second Tuesday {freq:'month',interval:1,monthly:{kind:'nth',n:2,weekday:1}}; yearly {freq:'year',interval:1}; every 2 days after done {freq:'day',interval:2,fromCompletion:true}. Weekdays: 0 Monday to 6 Sunday.
`reminders`	list of object	Reminders. {kind:'before',minutes:10} fires 10 minutes before the start (or before 09:00 for a task with no time); {kind:'day',offset:-1,time:1200} fires the day before at 20:00.
`note`	string	Markdown.
`event`	boolean	True for something attended (a class, a meeting) rather than ticked off.
`goalId`	string	The goal's id.

`update_task`

Change a task. Changes your plan.

Change fields of a task. Pass null to clear a field. Changing the date of a repeating task moves the whole series.

Field	Type	About
`taskId` (required)	string	The task's id.
`title`	string
`spaceId`	string or null	The space's id.
`date`	string or null	A date like 2026-10-13, in the person's own calendar.
`time`	integer, 0 to 1439 or null	Start time, in minutes after midnight (14:30 is 870).
`length`	integer, 1 to 1440 or null	Length in minutes. Leave it out unless the person said how long; never guess.
`deadline`	string or null	When it's due, if different from the day it's planned for.
`repeat`	object or null	How the task repeats. Examples: every Tue and Thu {freq:'week',interval:1,weekdays:[1,3]}; last day of each month {freq:'month',interval:1,monthly:{kind:'last'}}; second Tuesday {freq:'month',interval:1,monthly:{kind:'nth',n:2,weekday:1}}; yearly {freq:'year',interval:1}; every 2 days after done {freq:'day',interval:2,fromCompletion:true}. Weekdays: 0 Monday to 6 Sunday.
`reminders`	list of object or null	Reminders. {kind:'before',minutes:10} fires 10 minutes before the start (or before 09:00 for a task with no time); {kind:'day',offset:-1,time:1200} fires the day before at 20:00.
`note`	string or null	Markdown.
`event`	boolean or null	True for something attended (a class, a meeting) rather than ticked off.
`goalId`	string or null	The goal's id.

`complete_task`

Complete a task. Changes your plan.

Tick a task off. A repeating task moves to its next date.

Field	Type	About
`taskId` (required)	string	The task's id.

`reopen_task`

Reopen a task. Changes your plan.

Mark a finished task as not done.

Field	Type	About
`taskId` (required)	string	The task's id.

`delete_task`

Delete a task. Changes your plan.

Delete a task. The person can restore it from the app.

Field	Type	About
`taskId` (required)	string	The task's id.

`move_tasks`

Move tasks. Changes your plan.

Move tasks to a date, optionally at a time. Pass date null to unschedule.

Field	Type	About
`taskIds` (required)	list of string
`date` (required)	string or null	A date like 2026-10-13, in the person's own calendar.
`time`	integer, 0 to 1439 or null	Start time, in minutes after midnight (14:30 is 870).

`add_space`

Add a space. Changes your plan.

Add a space, optionally inside another one. Colour defaults to the parent's.

Field	Type	About
`name` (required)	string
`color`	one of "blue", "green", "orange", "purple", "red", "yellow", "teal", "pink"
`parentId`	string	The parent space's id.

`update_space`

Change a space. Changes your plan.

Rename a space, change its colour or parent, or replace its Markdown note.

Field	Type	About
`spaceId` (required)	string	The space's id.
`name`	string
`color`	one of "blue", "green", "orange", "purple", "red", "yellow", "teal", "pink"
`parentId`	string or null	The parent space's id.
`note`	string

`add_habit`

Add a habit. Changes your plan.

Add a habit with a weekly target (1 to 7 times a week).

Field	Type	About
`title` (required)	string
`target` (required)	integer, 1 to 7
`spaceId`	string	The space's id.

`check_habit`

Check a habit. Changes your plan.

Mark a habit done or not done on a day (today by default).

Field	Type	About
`habitId` (required)	string	The habit's id.
`done` (required)	boolean
`date`	string	A date like 2026-10-13, in the person's own calendar.

`add_goal`

Add a goal. Changes your plan.

Add a goal: a number to reach (kind 'number', e.g. 100 km) or a count of linked tasks to finish (kind 'tasks').

Field	Type	About
`title` (required)	string
`kind` (required)	one of "number", "tasks"
`target` (required)	number
`unit`	string
`dueDate`	string	A date like 2026-10-13, in the person's own calendar.
`spaceId`	string	The space's id.

`update_goal`

Change a goal. Changes your plan.

Update a goal's progress (`current`), target, unit or due date.

Field	Type	About
`goalId` (required)	string	The goal's id.
`title`	string
`target`	number
`current`	number
`unit`	string or null
`dueDate`	string or null	A date like 2026-10-13, in the person's own calendar.

`propose_plan`

Propose a plan. Changes your plan.

Propose new time blocks. They appear in the app as proposals the person accepts or discards, so use this for plans rather than add_task. Each block is a new task with a date, a time and a length.

Field	Type	About
`agent` (required)	string	Your name, shown to the person, like 'Claude'.
`blocks` (required)	list of object