Plaineo Public API

REST API v1 for tasks, files, categories, and recurring exceptions. The full machine-readable contract is available as OpenAPI JSON.

Authentication

All public API calls use an API key in the HTTP header X-API-Key. Keys can be created and managed in the Plaineo Developer Portal.

Keep the full key private. The portal shows the full value only when you create it; later lists show only the prefix.

curl https://api.plaineo.com/api/v1/tasks \
  -H "X-API-Key: sc_your_api_key"

GET /api/v1/tasks

List owned and accepted shared tasks

Path and query parameters

Name	Where	Type	Required	Description
`limit`	query	integer	optional	Maximum number of items to return.
`offset`	query	integer	optional	Number of items to skip for pagination.
`dateFrom`	query	string (date)	optional	Only include tasks on or after this date.
`dateTo`	query	string (date)	optional	Only include tasks on or before this date.
`categoryCode`	query	string	optional	Convenience category code for one of your own categories.
`search`	query	string	optional	Case-insensitive substring match against task title only.
`finished`	query	boolean	optional	Completion state.

Responses: 200 Task list, 401 Unauthorized

POST /api/v1/tasks

Create a task

Request body fields

Name	Where	Type	Required	Description
`id`	body	string	optional	Stable resource ID. You can provide one on create where supported, otherwise Plaineo generates it.
`title`	body	string	required	Task title.
`notes`	body	string	optional	Free-form task notes.
`date`	body	string (date)	optional	Task date in YYYY-MM-DD format.
`start`	body	string	optional	Optional task start time.
`end`	body	string	optional	Optional task end time.
`categoryId`	body	string	optional	Stable category ID to assign the task to.
`categoryCode`	body	string	optional	Convenience category code for one of your own categories.
`finished`	body	boolean	optional	Completion state.
`cancelled`	body	boolean	optional	Whether the task or recurring instance is cancelled.
`recurring`	body	object	optional	Recurring rule data for repeating tasks.
`subtasks`	body	array<object>	optional	Checklist/subtask items attached to the task.
`reminders`	body	array<value>	optional	Reminder definitions for the task.
`attachments`	body	array<object \| object>	optional	Inline file uploads or references to previously uploaded files.

Example JSON body

{
  "title": "Call dentist",
  "date": "2026-06-10"
}

Responses: 200 Created task, 400 BadRequest, 401 Unauthorized, 403 Forbidden

POST /api/v1/tasks/from-content

Create tasks from text, base64 content, or URL using AI extraction

Request body fields

Name	Where	Type	Required	Description
`text`	body	string	optional	Plain text to process.
`base64`	body	string	optional	Base64-encoded file or image content.
`url`	body	string	optional	Public URL of content to process.
`mimeType`	body	string	optional	MIME type, such as image/jpeg or application/pdf.
`fileName`	body	string	optional	Original file name, including extension.
`categoryCode`	body	string	optional	Convenience category code for one of your own categories.

Example JSON body

{
  "text": "Dentist appointment next Monday at 3pm"
}

Responses: 200 Created tasks, 400 BadRequest, 401 Unauthorized, 413 PayloadTooLarge, 422 Unprocessable

GET /api/v1/tasks/{id}

Get a task detail, including safe attachment metadata

Path and query parameters

Name	Where	Type	Required	Description
`id`	path	string	required	Stable resource ID. You can provide one on create where supported, otherwise Plaineo generates it.

Responses: 200 Task detail, 401 Unauthorized, 404 NotFound

PUT /api/v1/tasks/{id}

Update a task; shared recipients need write permission

Path and query parameters

Name	Where	Type	Required	Description
`id`	path	string	required	Stable resource ID. You can provide one on create where supported, otherwise Plaineo generates it.

Request body fields

Name	Where	Type	Required	Description
`title`	body	string	optional	Task title.
`notes`	body	string	optional	Free-form task notes.
`date`	body	string (date)	optional	Task date in YYYY-MM-DD format.
`start`	body	string	optional	Optional task start time.
`end`	body	string	optional	Optional task end time.
`categoryId`	body	string	optional	Stable category ID to assign the task to.
`categoryCode`	body	string	optional	Convenience category code for one of your own categories.
`finished`	body	boolean	optional	Completion state.
`cancelled`	body	boolean	optional	Whether the task or recurring instance is cancelled.
`recurring`	body	object	optional	Recurring rule data for repeating tasks.
`subtasks`	body	array<object>	optional	Checklist/subtask items attached to the task.
`reminders`	body	array<value>	optional	Reminder definitions for the task.
`attachments`	body	array<object \| object>	optional	Inline file uploads or references to previously uploaded files.

Example JSON body

{
  "notes": "Updated via API"
}

Responses: 200 Updated task, 401 Unauthorized, 403 Forbidden, 404 NotFound

DELETE /api/v1/tasks/{id}

Soft-delete a task; shared recipients need write permission

Path and query parameters

Name	Where	Type	Required	Description
`id`	path	string	required	Stable resource ID. You can provide one on create where supported, otherwise Plaineo generates it.

Responses: 200 Ok, 401 Unauthorized, 403 Forbidden, 404 NotFound

POST /api/v1/files

Upload a base64 file

Request body fields

Name	Where	Type	Required	Description
`id`	body	string	optional	Stable resource ID. You can provide one on create where supported, otherwise Plaineo generates it.
`fileName`	body	string	required	Original file name, including extension.
`mimeType`	body	string	required	MIME type, such as image/jpeg or application/pdf.
`base64`	body	string	required	Base64-encoded file or image content.
`thumbBase64`	body	string	optional	Optional base64-encoded thumbnail.
`description`	body	string	optional	Optional human-readable description.

Example JSON body

{
  "fileName": "receipt.jpg",
  "mimeType": "image/jpeg",
  "base64": "<base64>"
}

Responses: 201 File metadata, 400 BadRequest, 401 Unauthorized, 413 PayloadTooLarge

GET /api/v1/files/{id}

Get file metadata and base64 content

Path and query parameters

Name	Where	Type	Required	Description
`id`	path	string	required	Stable resource ID. You can provide one on create where supported, otherwise Plaineo generates it.
`onlyThumb`	query	boolean	optional	Return thumbnailBase64Content instead of base64Content.

Responses: 200 File DTO, 401 Unauthorized, 403 Forbidden, 404 NotFound

DELETE /api/v1/files/{id}

Soft-delete an owned file

Path and query parameters

Name	Where	Type	Required	Description
`id`	path	string	required	Stable resource ID. You can provide one on create where supported, otherwise Plaineo generates it.

Responses: 200 Ok, 401 Unauthorized, 403 Forbidden, 404 NotFound

GET /api/v1/categories

List owned and accepted shared categories

Responses: 200 Category list, 401 Unauthorized

GET /api/v1/recurring-exceptions/task/{taskId}

List exceptions for an accessible recurring task

Path and query parameters

Name	Where	Type	Required	Description
`taskId`	path	string	required	ID of the parent task.

Responses: 200 Exception list, 401 Unauthorized, 404 NotFound

POST /api/v1/recurring-exceptions/task/{taskId}

Create or upsert an exception; shared recipients need write permission

Path and query parameters

Name	Where	Type	Required	Description
`taskId`	path	string	required	ID of the parent task.

Request body fields

Name	Where	Type	Required	Description
`instanceDate`	body	string	optional	Date of the recurring task instance to override.
`cancelled`	body	boolean	optional	Whether the task or recurring instance is cancelled.
`finished`	body	boolean	optional	Completion state.
`comments`	body	array<object>	optional	Public comment objects for the task or recurring instance.

Example JSON body

{
  "instanceDate": "2026-06-10",
  "finished": true
}

Responses: 200 Updated existing exception, 201 Created exception, 401 Unauthorized, 403 Forbidden, 404 NotFound

PUT /api/v1/recurring-exceptions/{id}

Update an exception; shared recipients need write permission on the parent task

Path and query parameters

Name	Where	Type	Required	Description
`id`	path	string	required	Stable resource ID. You can provide one on create where supported, otherwise Plaineo generates it.

Request body fields

Name	Where	Type	Required	Description
`instanceDate`	body	string	optional	Date of the recurring task instance to override.
`cancelled`	body	boolean	optional	Whether the task or recurring instance is cancelled.
`finished`	body	boolean	optional	Completion state.
`comments`	body	array<object>	optional	Public comment objects for the task or recurring instance.

Example JSON body

{
  "finished": false
}

Responses: 200 Updated exception, 401 Unauthorized, 403 Forbidden, 404 NotFound