{ "openapi": "3.0.3", "info": { "title": "Daykite API", "version": "1", "description": "Events, calendars, availability, tasks, projects, routines, goals, the planner, insights, the assistant, bookings, notifications, webhooks, and the automation layer around them. The same API the DayKite apps use. Authenticate with a session cookie (the web app), a session token (the phone apps), or a bearer token (an API key or an OAuth access token). Endpoints marked `sessionAuth` take a session only \u2014 see docs/mobile-api.md." }, "servers": [ { "url": "/api/v1" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key (Settings \u2192 Developer) or an OAuth access token from POST /oauth/token." }, "sessionAuth": { "type": "http", "scheme": "bearer", "description": "A DayKite session token \u2014 what signing in from an app returns, sent as `Authorization: Bearer`. The endpoints marked with it are for the first-party apps: an API key or OAuth token is refused with 403 `session_required`." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] } } }, "Event": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "spaceId": { "type": "string", "format": "uuid" }, "calendarId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "meetingUrl": { "type": "string", "nullable": true }, "kind": { "type": "string", "enum": [ "meeting", "appointment", "focus", "personal", "routine", "travel", "break", "buffer", "deadline", "task", "holiday" ] }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "timeZone": { "type": "string" }, "allDay": { "type": "boolean" }, "busy": { "type": "boolean" }, "recurrenceRule": { "type": "string", "nullable": true } } } } }, "paths": { "/api-keys": { "get": { "summary": "List your API keys (never the key itself)", "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Create an API key \u2014 the full key is returned once", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "scopes" ], "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "environment": { "type": "string", "enum": [ "live", "test" ], "default": "live" } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/api-keys/{id}": { "delete": { "summary": "Revoke an API key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Revoked" } } } }, "/assistant/actions/{id}": { "post": { "summary": "Confirm or cancel a suggestion the assistant made", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Suggestion id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "confirm", "cancel" ] } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/assistant/conversations": { "get": { "summary": "Your assistant conversations", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "OK" } } }, "delete": { "summary": "Clear all assistant history", "security": [ { "sessionAuth": [] } ], "responses": { "204": { "description": "Cleared" } } } }, "/assistant/conversations/{id}": { "get": { "summary": "One conversation with its messages", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } }, "delete": { "summary": "Delete one conversation", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conversation id", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/assistant/feedback": { "post": { "summary": "Rate an assistant answer", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "messageId", "rating" ], "properties": { "messageId": { "type": "string" }, "rating": { "type": "string", "enum": [ "up", "down" ] }, "reason": { "type": "string" }, "comment": { "type": "string" } } } } } }, "responses": { "204": { "description": "Thanks" } } } }, "/assistant/messages": { "post": { "summary": "Send one turn to the assistant. The same assistant as the web app, recorded as the `mobile` surface", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string" }, "text": { "type": "string" }, "action": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/assistant/preferences": { "get": { "summary": "Assistant preferences: focus period, meeting length, retention", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "OK" } } }, "patch": { "summary": "Change assistant preferences", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "focusPeriod": { "type": "string" }, "meetingMinutes": { "type": "integer" }, "focusMinutes": { "type": "integer" }, "retentionDays": { "type": "integer" }, "improve": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/assistant/quick-actions": { "get": { "summary": "The quick-action buttons to offer", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "OK" } } } }, "/assistant/status": { "get": { "summary": "Whether an AI model is connected, and this month's usage", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "OK" } } } }, "/automations": { "get": { "summary": "Your automations", "security": [ { "bearerAuth": [ "automations:read" ] } ], "responses": { "200": { "description": "OK" } }, "description": "Each automation (a workflow) as a flat summary: its trigger type and the kinds of action it takes, whether it's on, how often it has run. `rules` repeats the list for older clients." }, "post": { "summary": "Add an automation from a trigger and a list of actions", "security": [ { "bearerAuth": [ "automations:write" ] } ], "responses": { "201": { "description": "OK" } }, "description": "Body: `{ name, enabled, trigger: { type, filters }, actions: [...] }`. It becomes a workflow with the actions chained in order, which can then be opened and extended in the builder." } }, "/automations/{id}": { "patch": { "summary": "Switch an automation on or off", "security": [ { "bearerAuth": [ "automations:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } }, "description": "Body: `{ isActive }`. Switching on is refused with 422 and a `problems` list until the automation is ready to run." }, "delete": { "summary": "Delete an automation", "security": [ { "bearerAuth": [ "automations:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "OK" } } } }, "/availability": { "get": { "summary": "A day as My Day shows it: events, routine periods, protected time and free stretches", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "First day, YYYY-MM-DD. Defaults to today where the person is", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "How many days, 1-14", "schema": { "type": "integer" } }, { "name": "purpose", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "meeting", "focus" ] } }, { "name": "preferred", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "morning", "afternoon", "evening" ] } } ], "responses": { "200": { "description": "OK" } } } }, "/available-slots": { "get": { "summary": "Free windows across the next several days", "security": [ { "bearerAuth": [ "availability:read" ] } ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "YYYY-MM-DD, defaults to today" }, { "name": "days", "in": "query", "schema": { "type": "integer", "default": 7 } }, { "name": "minimumMinutes", "in": "query", "schema": { "type": "integer", "default": 30 } } ], "responses": { "200": { "description": "OK" } } } }, "/bookings": { "get": { "summary": "What people have booked with you", "security": [ { "bearerAuth": [ "bookings:read" ] } ], "responses": { "200": { "description": "OK" } } } }, "/bookings/{id}/cancel": { "post": { "summary": "Cancel a booking and tell the guest", "security": [ { "bearerAuth": [ "bookings:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/bookings/{id}/reschedule": { "get": { "summary": "The times this booking could move to", "security": [ { "bearerAuth": [ "bookings:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Move a booking to a new time", "security": [ { "bearerAuth": [ "bookings:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/bug-reports": { "get": { "summary": "Bug reports you've filed", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Report a bug", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "expected": { "type": "string" }, "pagePath": { "type": "string" }, "diagnostics": { "type": "object" } } } } } }, "responses": { "201": { "description": "Filed" } } } }, "/calendars": { "get": { "summary": "List your calendars", "security": [ { "bearerAuth": [ "calendars:read" ] } ], "responses": { "200": { "description": "OK" } } } }, "/devices": { "get": { "summary": "Devices you're signed in on", "security": [ { "bearerAuth": [ "devices:write" ] } ], "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Register a device for push. Re-registering the same token updates that device rather than adding another", "security": [ { "bearerAuth": [ "devices:write" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "platform" ], "properties": { "platform": { "type": "string", "description": "ios, android, web" }, "name": { "type": "string" }, "pushToken": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated" }, "201": { "description": "Created" } } } }, "/devices/{id}": { "delete": { "summary": "Forget a device, so it stops receiving push", "security": [ { "bearerAuth": [ "devices:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Gone" } } } }, "/devices/{id}/test": { "post": { "summary": "Send a test notification to one device", "security": [ { "bearerAuth": [ "devices:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Device id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sent" }, "409": { "description": "That device has no push token" } } } }, "/event-types": { "get": { "summary": "The built-in kinds and your own event types", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Create an event type", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "color" ], "properties": { "name": { "type": "string" }, "color": { "type": "string" }, "baseKind": { "type": "string" }, "defaultMinutes": { "type": "integer" } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/event-types/{id}": { "patch": { "summary": "Change an event type", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Event type id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK" } } }, "delete": { "summary": "Delete an event type", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Event type id", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/events": { "get": { "summary": "List events in a range", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "space", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Repeatable Space id filter." } ], "security": [ { "bearerAuth": [ "events:read" ] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } } } } } }, "post": { "summary": "Create an event", "security": [ { "bearerAuth": [ "events:create" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "$ref": "#/components/schemas/Event" } } } } } }, "409": { "description": "Time or resource conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/events/{id}": { "get": { "summary": "Get an event", "security": [ { "bearerAuth": [ "events:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not found" } } }, "patch": { "summary": "Update an event (whole series \u2014 see docs for the app-only per-occurrence editing)", "security": [ { "bearerAuth": [ "events:update" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "409": { "description": "Resource conflict" } } }, "delete": { "summary": "Cancel an event", "security": [ { "bearerAuth": [ "events:delete" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Cancelled" } } } }, "/events/{id}/rsvp": { "post": { "summary": "Answer an invitation: yes, no or maybe", "security": [ { "bearerAuth": [ "events:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/focus": { "get": { "summary": "The focus session running or paused right now", "security": [ { "bearerAuth": [ "tasks:read" ] } ], "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Start a focus session", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "eventId": { "type": "string" }, "minutes": { "type": "integer" }, "label": { "type": "string" } } } } } }, "responses": { "201": { "description": "Started" }, "409": { "description": "One is already running" } } } }, "/focus/{id}": { "patch": { "summary": "Pause, resume or stop a focus session", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Focus session id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "pause", "resume", "stop" ] } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/free-busy": { "get": { "summary": "Busy intervals in a range", "security": [ { "bearerAuth": [ "availability:read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK" } } } }, "/goals": { "get": { "summary": "Your weekly time goals, with this week's planned and done time", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Create a goal", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "weeklyMinutes" ], "properties": { "name": { "type": "string" }, "weeklyMinutes": { "type": "integer" }, "preferredPeriod": { "type": "string" }, "minBlockMinutes": { "type": "integer" }, "maxBlockMinutes": { "type": "integer" }, "deadline": { "type": "string" }, "color": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/goals/{id}": { "put": { "summary": "Change a goal", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Goal id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "weeklyMinutes": { "type": "integer" } } } } } }, "responses": { "200": { "description": "OK" } } }, "delete": { "summary": "Delete a goal", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Goal id", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/inbox": { "get": { "summary": "What's waiting: invitations, requests and things to answer", "security": [ { "bearerAuth": [ "events:read" ] } ], "responses": { "200": { "description": "OK" } } } }, "/inbox/count": { "get": { "summary": "How many things are waiting, for a badge", "security": [ { "bearerAuth": [ "events:read" ] } ], "responses": { "200": { "description": "OK" } } } }, "/insights": { "get": { "summary": "Where the week's time went", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Monday of the week, YYYY-MM-DD", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/me": { "get": { "summary": "Your profile, modules and preferences", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "OK" } } }, "patch": { "summary": "Change your profile, time zone, week start, modules or preferences", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "timeZone": { "type": "string" }, "weekStartsOn": { "type": "integer" }, "enabledModules": { "type": "object", "additionalProperties": { "type": "boolean" } }, "preferences": { "type": "object" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/me/bootstrap": { "get": { "summary": "Everything an app needs to draw its first screen: you, your Spaces, your calendars, and the server clock to sync from", "security": [ { "bearerAuth": [ "spaces:read" ] } ], "responses": { "200": { "description": "OK" } } } }, "/me/plan": { "get": { "summary": "Your plan, this month's AI answers, the plans on offer, and where to upgrade (the website)", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "OK" } } } }, "/meeting-types": { "get": { "summary": "The kinds of meeting you offer", "security": [ { "bearerAuth": [ "bookings:read" ] } ], "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Create a meeting type", "security": [ { "bearerAuth": [ "bookings:write" ] } ], "responses": { "201": { "description": "OK" } } }, "patch": { "summary": "Edit a meeting type (id in the body)", "security": [ { "bearerAuth": [ "bookings:write" ] } ], "responses": { "200": { "description": "OK" } } }, "delete": { "summary": "Delete a meeting type (?id=). Refused once people have booked it \u2014 switch it off instead.", "security": [ { "bearerAuth": [ "bookings:write" ] } ], "responses": { "204": { "description": "OK" } }, "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/notifications": { "get": { "summary": "Your notifications", "security": [ { "bearerAuth": [ "notifications:read" ] } ], "parameters": [ { "name": "unread", "in": "query", "required": false, "description": "1 for unread only", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } }, "patch": { "summary": "Mark every notification read", "security": [ { "bearerAuth": [ "notifications:write" ] } ], "responses": { "200": { "description": "OK" } } } }, "/oauth/applications": { "get": { "summary": "List OAuth apps you've registered", "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Register an OAuth app \u2014 the client secret is returned once", "responses": { "201": { "description": "Created" } } } }, "/oauth/applications/{id}": { "delete": { "summary": "Deregister an app", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/oauth/token": { "post": { "summary": "Exchange an authorization code or refresh token for an access token", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ] }, "code": { "type": "string" }, "refresh_token": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "redirect_uri": { "type": "string" } } } } } }, "responses": { "200": { "description": "A standard OAuth2 token response" } } } }, "/organizations": { "get": { "summary": "The organizations you're part of", "security": [ { "bearerAuth": [ "organizations:read" ] } ], "responses": { "200": { "description": "OK" } } } }, "/planner/apply": { "post": { "summary": "Write the proposed blocks the person kept to the calendar", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "blocks" ], "properties": { "blocks": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/planner/plan": { "post": { "summary": "Propose blocks for tasks or goals. Nothing is written", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "tasks", "goals" ] }, "from": { "type": "string" }, "to": { "type": "string" }, "ids": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/projects": { "get": { "summary": "Projects you're in, with counts and People", "security": [ { "bearerAuth": [ "projects:read" ] } ], "parameters": [ { "name": "archived", "in": "query", "required": false, "description": "1 to list archived projects instead", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/projects/{id}": { "get": { "summary": "One project, with its lists, members and tasks", "security": [ { "bearerAuth": [ "projects:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } }, "patch": { "summary": "Rename a project, archive it, or change its colour", "security": [ { "bearerAuth": [ "projects:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } }, "delete": { "summary": "Delete a project and everything in it", "security": [ { "bearerAuth": [ "projects:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "OK" } } } }, "/projects/{id}/lists": { "post": { "summary": "Add a column to a project's board", "security": [ { "bearerAuth": [ "projects:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "OK" } } } }, "/routines": { "get": { "summary": "Your routines, each with its periods", "security": [ { "bearerAuth": [ "routines:read" ] } ], "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Create a routine with its periods and their tasks", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "days", "periods" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "personal", "work" ] }, "color": { "type": "string" }, "days": { "type": "array", "items": { "type": "integer" } }, "periods": { "type": "array", "items": { "type": "object", "required": [ "name", "startMinute", "endMinute" ], "properties": { "name": { "type": "string" }, "startMinute": { "type": "integer" }, "endMinute": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" } } } }, "windowStartMinute": { "type": "integer" }, "windowEndMinute": { "type": "integer" }, "priority": { "type": "string", "enum": [ "low", "normal", "high" ] }, "canMove": { "type": "boolean" } } } } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/routines/conflicts": { "get": { "summary": "Routine periods an event has landed on, each with a suggested new time", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "YYYY-MM-DD", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "How many days to look ahead", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/routines/instances": { "get": { "summary": "Each period on each date: status, that day's times, and its tasks", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "YYYY-MM-DD", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": true, "description": "YYYY-MM-DD", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/routines/items/{itemId}/days/{date}": { "put": { "summary": "Tick one of a period's tasks off for that day", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "itemId", "in": "path", "required": true, "description": "Routine task id", "schema": { "type": "string" } }, { "name": "date", "in": "path", "required": true, "description": "YYYY-MM-DD", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "done" ], "properties": { "done": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/routines/periods/{periodId}/days/{date}": { "put": { "summary": "Mark a period done or skipped for one day, or move it", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "periodId", "in": "path", "required": true, "description": "Period id", "schema": { "type": "string" } }, { "name": "date", "in": "path", "required": true, "description": "YYYY-MM-DD", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "done", "skipped" ], "nullable": true }, "startMinute": { "type": "integer" }, "endMinute": { "type": "integer" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/routines/{id}": { "get": { "summary": "One routine, its periods and their tasks", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Routine id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } }, "patch": { "summary": "Change a routine. `periods`, when sent, is the full new list", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Routine id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "color": { "type": "string" }, "isActive": { "type": "boolean" }, "days": { "type": "array", "items": { "type": "integer" } }, "periods": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "OK" } } }, "delete": { "summary": "Delete a routine", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Routine id", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/spaces": { "get": { "summary": "The Spaces you belong to", "security": [ { "bearerAuth": [ "spaces:read" ] } ], "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Create a Space", "security": [ { "bearerAuth": [ "spaces:write" ] } ], "responses": { "201": { "description": "Created" } } } }, "/spaces/{id}": { "get": { "summary": "One Space, with its calendars and members", "security": [ { "bearerAuth": [ "spaces:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } }, "patch": { "summary": "Rename a Space, or change its colour and default visibility", "security": [ { "bearerAuth": [ "spaces:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } }, "delete": { "summary": "Delete a Space and everything it owns", "security": [ { "bearerAuth": [ "spaces:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "OK" } } } }, "/spaces/{id}/members": { "get": { "summary": "Who is in a Space", "security": [ { "bearerAuth": [ "spaces:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Invite somebody to a Space", "security": [ { "bearerAuth": [ "spaces:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "OK" } } }, "patch": { "summary": "Change somebody's role or visibility", "security": [ { "bearerAuth": [ "spaces:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } }, "delete": { "summary": "Remove somebody from a Space", "security": [ { "bearerAuth": [ "spaces:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "OK" } } } }, "/sync": { "get": { "summary": "Everything that changed since a timestamp. Without `since`, a full snapshot. Deletions arrive as rows carrying deletedAt, and as entries in `deleted`", "security": [ { "bearerAuth": [ "sync:read" ] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "description": "ISO 8601 timestamp from a previous sync's `syncedAt`", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/task-lists": { "get": { "summary": "Your own lists \u2014 the ones that belong to no project", "security": [ { "bearerAuth": [ "tasks:read" ] } ], "responses": { "200": { "description": "OK" } } } }, "/tasks": { "get": { "summary": "List tasks you can see, with their project, list and assignees", "security": [ { "bearerAuth": [ "tasks:read" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Exact status, e.g. todo", "schema": { "type": "string" } }, { "name": "open", "in": "query", "required": false, "description": "1 for everything not yet done", "schema": { "type": "string" } }, { "name": "due", "in": "query", "required": false, "description": "Due on this date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Due on or after this date", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Due on or before this date", "schema": { "type": "string" } }, { "name": "assignee", "in": "query", "required": false, "description": "me, for tasks assigned to you", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/time-protections": { "get": { "summary": "Standing rules that keep time free", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Create a protection", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "days": { "type": "array", "items": { "type": "integer" } }, "startMinute": { "type": "integer" }, "endMinute": { "type": "integer" }, "kind": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/time-protections/{id}": { "put": { "summary": "Change a protection", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Protection id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK" } } }, "delete": { "summary": "Delete a protection", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Protection id", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/webhook-deliveries": { "get": { "summary": "List deliveries, optionally filtered by webhook", "parameters": [ { "name": "webhookId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/webhook-deliveries/{id}": { "get": { "summary": "Get one delivery, including the raw response", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/webhook-deliveries/{id}/retry": { "post": { "summary": "Manually retry or replay a delivery", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/webhooks": { "get": { "summary": "List your webhooks", "responses": { "200": { "description": "OK" } } }, "post": { "summary": "Create a webhook \u2014 the signing secret is returned once", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "endpointUrl", "events" ], "properties": { "name": { "type": "string" }, "endpointUrl": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event catalog types, or [\"*\"] for everything." } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/webhooks/{id}": { "patch": { "summary": "Update a webhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } }, "delete": { "summary": "Delete a webhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/webhooks/{id}/rotate-secret": { "post": { "summary": "Rotate the signing secret \u2014 the new one is returned once", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/webhooks/{id}/test": { "post": { "summary": "Send one synthetic delivery immediately, bypassing the queue", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The raw response from your endpoint" } } } } } }