Views API
The agenda, saved and built-in views
GET /agenda
The agenda across every hat visible now, each line tagged with its org.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
span | query | string | day (default), week, fortnight or month. |
start | query | string (date) | The first day (YYYY-MM-DD; default today, or the week or month containing it). |
q | query | string | Only entries matching this query (§9.1). |
tz | query | string | The viewer's IANA zone for floating times and relative dates (default: the account's). |
Responses
200- OK. Agenda
application/json
GET /orgs/{org}/agenda
The agenda (§8.5) for a span, in your zone.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
span | query | string | day (default), week, fortnight or month. |
start | query | string (date) | The first day (YYYY-MM-DD; default today, or the week or month containing it). |
q | query | string | Only entries matching this query (§9.1). |
tz | query | string | The viewer's IANA zone for floating times and relative dates (default: the account's). |
Responses
200- OK. Agenda
application/json
GET /orgs/{org}/agenda-commands
Agenda commands defined on pages you can read.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
Responses
200- OK. Paged_AgendaCommand
application/json
GET /orgs/{org}/agenda-commands/{key}/results
Runs a block agenda (§9.5).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
key required | path | string | The command's key. |
start | query | string (date) | The first day for agenda blocks (default: today, or its week). |
tz | query | string | The viewer's IANA zone for floating times and relative dates (default: the account's). |
Responses
200- OK. CommandResults
application/json
GET /orgs/{org}/views
Built-in views, then your views and your spaces' views.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
Responses
200- OK. Paged_SavedView
application/json
POST /orgs/{org}/views
Saves a view.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
Request body
application/json, ViewBody.
| Field | Type | Description |
|---|---|---|
config | object | null | Layout options. |
layout | string | null | Layout. |
name | string | null | Name. |
position | integer (int32) | null | Order. |
query | string | null | The query. |
space | string | null | Share it in a space (slug); "" makes it personal again. |
Responses
201- Created. SavedView
application/json
PATCH /orgs/{org}/views/{ref}
Updates a view.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The view's short ID, or a built-in (agenda, tasks, inbox, mine, review, team:<handle>). |
Request body
application/json, ViewBody.
| Field | Type | Description |
|---|---|---|
config | object | null | Layout options. |
layout | string | null | Layout. |
name | string | null | Name. |
position | integer (int32) | null | Order. |
query | string | null | The query. |
space | string | null | Share it in a space (slug); "" makes it personal again. |
Responses
200- OK. SavedView
application/json
DELETE /orgs/{org}/views/{ref}
Deletes a view.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The view's short ID, or a built-in (agenda, tasks, inbox, mine, review, team:<handle>). |
Responses
204- No content
GET /orgs/{org}/views/{ref}/results
A view's results: tasks in rank (or the view's) order, with board columns or an agenda as the layout needs.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
org required | path | string | The org slug. |
ref required | path | string | The view's short ID, or a built-in (agenda, tasks, inbox, mine, review, team:<handle>). |
limit | query | integer (int32) | Page size. |
cursor | query | string | Cursor. |
span | query | string | For agenda and calendar layouts: the span. |
start | query | string (date) | For agenda and calendar layouts: the first day. |
tz | query | string | The viewer's IANA zone for floating times and relative dates (default: the account's). |
Responses
200- OK. ViewResults
application/json
GET /tasks
Tasks across every hat visible now.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
q | query | string | A query (default: open tasks that are yours). |
limit | query | integer (int32) | At most this many per hat (default 50). |
tz | query | string | The viewer's IANA zone for floating times and relative dates (default: the account's). |
Responses
200- OK. Paged_HatTask
application/json