{ "openapi": "3.1.0", "info": { "title": "Plaineo Public API", "version": "1.0.0", "summary": "Public REST API v1 for tasks, files, categories, and recurring exceptions." }, "servers": [ { "url": "https://api.plaineo.com", "description": "Production" }, { "url": "http://localhost:5001/sc-firebase-8526b/europe-west1/api", "description": "Local Firebase emulator" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Tasks" }, { "name": "Files" }, { "name": "Categories" }, { "name": "Recurring Exceptions" } ], "paths": { "/api/v1/openapi.json": { "get": { "operationId": "getOpenApi", "tags": [ "Reference" ], "summary": "Get the OpenAPI document", "security": [], "responses": { "200": { "description": "OpenAPI document" } } } }, "/api/v1/tasks": { "get": { "operationId": "listTasks", "tags": [ "Tasks" ], "summary": "List owned and accepted shared tasks", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "dateFrom", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "dateTo", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "categoryCode", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive substring match against task title only." }, { "name": "finished", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Task list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "createTask", "tags": [ "Tasks" ], "summary": "Create a task", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTaskRequest" }, "examples": { "minimal": { "value": { "title": "Call dentist", "date": "2026-06-10" } } } } } }, "responses": { "200": { "description": "Created task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/tasks/from-content": { "post": { "operationId": "createTaskFromContent", "tags": [ "Tasks" ], "summary": "Create tasks from text, base64 content, or URL using AI extraction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFromContentRequest" }, "examples": { "text": { "value": { "text": "Dentist appointment next Monday at 3pm" } } } } } }, "responses": { "200": { "description": "Created tasks", "content": { "application/json": { "schema": { "type": "object", "required": [ "tasks" ], "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/tasks/{id}": { "get": { "operationId": "getTask", "tags": [ "Tasks" ], "summary": "Get a task detail, including safe attachment metadata", "parameters": [ { "$ref": "#/components/parameters/TaskId" } ], "responses": { "200": { "description": "Task detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateTask", "tags": [ "Tasks" ], "summary": "Update a task; shared recipients need write permission", "parameters": [ { "$ref": "#/components/parameters/TaskId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTaskRequest" }, "examples": { "notes": { "value": { "notes": "Updated via API" } } } } } }, "responses": { "200": { "description": "Updated task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteTask", "tags": [ "Tasks" ], "summary": "Soft-delete a task; shared recipients need write permission", "parameters": [ { "$ref": "#/components/parameters/TaskId" } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/files": { "post": { "operationId": "uploadFile", "tags": [ "Files" ], "summary": "Upload a base64 file", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadFileRequest" }, "examples": { "image": { "value": { "fileName": "receipt.jpg", "mimeType": "image/jpeg", "base64": "" } } } } } }, "responses": { "201": { "description": "File metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" } } } }, "/api/v1/files/{id}": { "get": { "operationId": "getFile", "tags": [ "Files" ], "summary": "Get file metadata and base64 content", "parameters": [ { "$ref": "#/components/parameters/FileId" }, { "name": "onlyThumb", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Return thumbnailBase64Content instead of base64Content." } ], "responses": { "200": { "description": "File DTO", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteFile", "tags": [ "Files" ], "summary": "Soft-delete an owned file", "parameters": [ { "$ref": "#/components/parameters/FileId" } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/categories": { "get": { "operationId": "listCategories", "tags": [ "Categories" ], "summary": "List owned and accepted shared categories", "responses": { "200": { "description": "Category list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/recurring-exceptions/task/{taskId}": { "get": { "operationId": "listRecurringExceptions", "tags": [ "Recurring Exceptions" ], "summary": "List exceptions for an accessible recurring task", "parameters": [ { "$ref": "#/components/parameters/TaskIdPath" } ], "responses": { "200": { "description": "Exception list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringException" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "createRecurringException", "tags": [ "Recurring Exceptions" ], "summary": "Create or upsert an exception; shared recipients need write permission", "parameters": [ { "$ref": "#/components/parameters/TaskIdPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringExceptionWrite" }, "examples": { "finished": { "value": { "instanceDate": "2026-06-10", "finished": true } } } } } }, "responses": { "200": { "description": "Updated existing exception", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringException" } } } }, "201": { "description": "Created exception", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringException" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/recurring-exceptions/{id}": { "put": { "operationId": "updateRecurringException", "tags": [ "Recurring Exceptions" ], "summary": "Update an exception; shared recipients need write permission on the parent task", "parameters": [ { "$ref": "#/components/parameters/ExceptionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringExceptionWrite" }, "examples": { "unfinished": { "value": { "finished": false } } } } } }, "responses": { "200": { "description": "Updated exception", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringException" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "parameters": { "TaskId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, "TaskIdPath": { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } }, "FileId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, "ExceptionId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } }, "responses": { "Ok": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "const": true } } } } } }, "BadRequest": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The API key user does not have the required permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found or not visible to this API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PayloadTooLarge": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unprocessable": { "description": "Request could not be processed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } }, "additionalProperties": false }, "Permissions": { "type": "object", "required": [ "read", "write", "share" ], "properties": { "read": { "const": true }, "write": { "type": "boolean" }, "share": { "type": "boolean" } }, "additionalProperties": false }, "Participant": { "type": "object", "required": [ "participantId", "permissions" ], "properties": { "participantId": { "type": "string" }, "permissions": { "$ref": "#/components/schemas/Permissions" } }, "additionalProperties": false }, "Access": { "type": "object", "required": [ "access", "ownerId", "permissions" ], "properties": { "access": { "enum": [ "owner", "shared" ] }, "ownerId": { "type": "string" }, "shareId": { "type": "string" }, "permissions": { "$ref": "#/components/schemas/Permissions" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } } }, "additionalProperties": false }, "Comment": { "type": "object", "required": [ "id", "text", "authorId", "createdAt" ], "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "authorId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "editedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "Subtask": { "type": "object", "required": [ "text" ], "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "finished": { "type": "boolean" }, "deleted": { "type": "boolean" } }, "additionalProperties": false }, "TaskAttachment": { "type": "object", "required": [ "fileId", "thumbnailAvailable" ], "properties": { "fileId": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "fileType": { "type": "string" }, "fileSize": { "type": "integer" }, "description": { "type": "string" }, "order": { "type": "number" }, "addedAt": { "type": "string", "format": "date-time" }, "thumbnailAvailable": { "type": "boolean" } }, "additionalProperties": false }, "Task": { "type": "object", "required": [ "id", "title", "access" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "allDay": { "type": "boolean" }, "categoryId": { "type": "string" }, "categoryCode": { "type": "string" }, "finished": { "type": "boolean" }, "cancelled": { "type": "boolean" }, "assignment": { "type": "string" }, "week": { "type": "object" }, "locationText": { "type": "string" }, "titleImageId": { "type": "string" }, "listOrder": { "type": "number" }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } }, "subtasks": { "type": "array", "items": { "$ref": "#/components/schemas/Subtask" } }, "metadata": { "type": "object", "additionalProperties": true }, "customFields": { "type": "object", "additionalProperties": true }, "recurring": { "type": "object", "additionalProperties": true }, "recurrenceUnmapped": { "type": "boolean" }, "reminders": { "type": "array", "items": {} }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/TaskAttachment" } }, "access": { "$ref": "#/components/schemas/Access" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CreateTaskRequest": { "type": "object", "required": [ "title" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "categoryId": { "type": "string" }, "categoryCode": { "type": "string" }, "finished": { "type": "boolean" }, "cancelled": { "type": "boolean" }, "recurring": { "type": "object", "additionalProperties": true }, "subtasks": { "type": "array", "items": { "$ref": "#/components/schemas/Subtask" } }, "reminders": { "type": "array", "items": {} }, "attachments": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/InlineAttachmentInput" }, { "$ref": "#/components/schemas/FileAttachmentInput" } ] } } }, "additionalProperties": false }, "UpdateTaskRequest": { "type": "object", "properties": { "title": { "type": "string" }, "notes": { "type": "string" }, "date": { "type": "string", "format": "date" }, "start": { "type": "string" }, "end": { "type": "string" }, "categoryId": { "type": "string" }, "categoryCode": { "type": "string" }, "finished": { "type": "boolean" }, "cancelled": { "type": "boolean" }, "recurring": { "type": "object", "additionalProperties": true }, "subtasks": { "type": "array", "items": { "$ref": "#/components/schemas/Subtask" } }, "reminders": { "type": "array", "items": {} }, "attachments": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/InlineAttachmentInput" }, { "$ref": "#/components/schemas/FileAttachmentInput" } ] } } }, "additionalProperties": false }, "InlineAttachmentInput": { "type": "object", "required": [ "fileName", "mimeType", "base64" ], "properties": { "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "base64": { "type": "string" }, "thumbBase64": { "type": "string" }, "order": { "type": "number" } }, "additionalProperties": false }, "FileAttachmentInput": { "type": "object", "required": [ "fileId" ], "properties": { "fileId": { "type": "string" }, "order": { "type": "number" } }, "additionalProperties": false }, "CreateFromContentRequest": { "type": "object", "properties": { "text": { "type": "string" }, "base64": { "type": "string" }, "url": { "type": "string" }, "mimeType": { "type": "string" }, "fileName": { "type": "string" }, "categoryCode": { "type": "string" } }, "additionalProperties": false }, "UploadFileRequest": { "type": "object", "required": [ "fileName", "mimeType", "base64" ], "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "base64": { "type": "string" }, "thumbBase64": { "type": "string" }, "description": { "type": "string" } }, "additionalProperties": false }, "File": { "type": "object", "required": [ "id", "fileName", "mimeType", "fileType", "access" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "fileType": { "type": "string" }, "description": { "type": "string" }, "fileSize": { "type": "integer" }, "thumbnailAvailable": { "type": "boolean" }, "base64Content": { "type": "string" }, "thumbnailBase64Content": { "type": "string" }, "access": { "$ref": "#/components/schemas/Access" } } }, "Category": { "type": "object", "required": [ "id", "code", "access" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" }, "icon": { "type": "string" }, "isBuiltIn": { "type": "boolean" }, "access": { "$ref": "#/components/schemas/Access" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } } } }, "RecurringException": { "type": "object", "required": [ "id", "taskId", "instanceDate", "createdAt", "access" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "taskId": { "type": "string" }, "instanceDate": { "type": "string" }, "cancelled": { "type": "boolean" }, "finished": { "type": "boolean" }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } }, "standaloneTaskId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "access": { "$ref": "#/components/schemas/Access" } } }, "RecurringExceptionWrite": { "type": "object", "properties": { "instanceDate": { "type": "string" }, "cancelled": { "type": "boolean" }, "finished": { "type": "boolean" }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } } }, "additionalProperties": false } } } }