Plaineo Public API

REST API v1 for tasks, files, categories, groups, search, 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.
includeParticipants query boolean optional Include full access participant metadata. Defaults to false for faster list/search/agent reads.

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 a task.
attachments body array<object | object> optional Inline file uploads or references to previously uploaded files.
comments body array<object> optional Public comment objects for the task or recurring instance.
customFields body object optional
metadata body object optional

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.
idempotencyKey body string optional Optional stable key supplied by the caller. Reusing the same key for the same request prevents duplicate task/file documents on retries.

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.
include query string optional Comma-separated optional sections. Supported values: attachments,comments,subtasks,notes,metadata,customFields,recurring,reminders,all. When omitted, default full task DTO behavior is preserved.

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 a task.
attachments body array<object | object> optional Inline file uploads or references to previously uploaded files.
comments body array<object> optional Public comment objects for the task or recurring instance.
customFields body object optional
metadata body object optional

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

Path and query parameters

Name Where Type Required Description
includeParticipants query boolean optional Include full access participant metadata. Defaults to false for faster list/search/agent reads.

Responses: 200 Category list, 401 Unauthorized

POST /api/v1/categories

Create a custom category with optional custom field schema

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.
code body string required
name body string optional
color body string optional
icon body string optional
resultStructure body array<object> optional
voiceTextDescription body string optional
imageDescription body string optional
keywords body array<string> optional
enabledForImage body boolean optional
enabledForVoiceText body boolean optional

Example JSON body

{
  "code": "api_smoke",
  "name": "API Smoke",
  "resultStructure": [
    {
      "param": "severity",
      "type": "text",
      "description": "Severity label"
    },
    {
      "param": "referenceUrl",
      "type": "url",
      "description": "Related issue or document URL"
    }
  ]
}

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

GET /api/v1/categories/{id}

Get one category by id or code

Path and query parameters

Name Where Type Required Description
id path string required Category id or category code.

Responses: 200 Category, 401 Unauthorized, 404 NotFound

PUT /api/v1/categories/{id}

Update a custom category by id or code

Path and query parameters

Name Where Type Required Description
id path string required Category id or category code.

Request body fields

Name Where Type Required Description
name body string optional
color body string optional
icon body string optional
resultStructure body array<object> optional
voiceTextDescription body string optional
imageDescription body string optional
keywords body array<string> optional
enabledForImage body boolean optional
enabledForVoiceText body boolean optional

Responses: 200 Updated category, 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound

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

GET /api/v1/groups

List visible category groups and share groups

Path and query parameters

Name Where Type Required Description
search query string optional Case-insensitive substring match against group name, code, id, type, or category codes.
includeStats query boolean optional Include task counts for each group.
includeParticipants query boolean optional Include full access participant metadata. Defaults to false for faster list/search/agent reads.

Responses: 200 Group list, 401 Unauthorized

GET /api/v1/groups/{id}

Get a visible group by id or code

Path and query parameters

Name Where Type Required Description
id path string required Group id or group code.
includeParticipants query boolean optional Include full access participant metadata. Defaults to false for faster list/search/agent reads.

Responses: 200 Group detail, 401 Unauthorized, 404 NotFound

PUT /api/v1/groups/{id}/categories

Update category membership for an owned category group

Use categoryCodes to replace the full membership, or add/remove to patch it. Only category-group records owned by the API-key user can be updated.

Path and query parameters

Name Where Type Required Description
id path string required Group id or group code.

Request body fields

Name Where Type Required Description
categoryCodes body array<string> optional Full replacement list of category codes for a category group.
add body array<string> optional Category codes to add to a category group.
remove body array<string> optional Category codes to remove from a category group.

Example JSON body

{
  "add": [
    "automation"
  ]
}

Responses: 200 Updated group, 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound

GET /api/v1/groups/{id}/tasks

List tasks resolved under a group

Path and query parameters

Name Where Type Required Description
id path string required Group id or group code.
limit query integer optional Maximum number of items to return.
offset query integer optional Number of items to skip for pagination.
includeParticipants query boolean optional Include full access participant metadata. Defaults to false for faster list/search/agent reads.

Responses: 200 Tasks in group, 401 Unauthorized, 404 NotFound

GET /api/v1/groups/{id}/context

Get compact group context with counts, category breakdown, and representative tasks

Path and query parameters

Name Where Type Required Description
id path string required Group id or group code.
limit query integer optional Maximum recent/unfinished tasks returned in each list.

Responses: 200 Group context, 401 Unauthorized, 404 NotFound

GET /api/v1/search

Search visible tasks, groups, and categories using indexed task search by default

Task search uses the compact search index by default. Scoped task search with categoryCode or groupId avoids global scans. Existing unindexed accounts fall back to an exhaustive scan until POST /api/v1/search/reindex is run.

Path and query parameters

Name Where Type Required Description
q query string required Search text.
types query string optional Comma-separated subset: tasks,groups,categories.
limit query integer optional Maximum number of items to return.
categoryCode query string optional Optional fast task-search scope: only search tasks in this category code.
groupId query string optional Optional fast task-search scope: only search tasks in this group id or code.
scope query "indexed" | "all" optional Task search scope. Default uses the compact task search index. Use all to force the slower exhaustive task scan fallback.

Responses: 200 Search results, 400 BadRequest, 401 Unauthorized

GET /api/v1/categories/{id}/tasks

List tasks in a category by id or code

Path and query parameters

Name Where Type Required Description
id path string required Category id or category code.
limit query integer optional Maximum number of items to return.
offset query integer optional Number of items to skip for pagination.
finished query boolean optional Completion state.
search query string optional Case-insensitive title substring search.
hasComments query boolean optional Only include tasks that have at least one non-deleted comment when true, or no visible comments when false.
hasAttachments query boolean optional Only include tasks that have attachments when true, or no attachments when false.
attachmentMimeType query string optional Only include tasks with an attachment matching this MIME type or prefix, e.g. image/ or image/jpeg.
include query string optional Comma-separated optional sections. Supported values: attachments,comments,subtasks,notes,metadata,customFields,recurring,reminders,all. When omitted, default full task DTO behavior is preserved.

Responses: 200 Tasks in category, 401 Unauthorized, 404 NotFound

GET /api/v1/categories/{id}/context

Get compact category context with task, photo, and comment counts

Path and query parameters

Name Where Type Required Description
id path string required Category id or category code.
limit query integer optional Maximum recent/unfinished tasks returned in each list.

Responses: 200 Category context, 401 Unauthorized, 404 NotFound

GET /api/v1/files/{id}/inspect

Inspect file metadata and thumbnail readability

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 File inspection, 401 Unauthorized, 403 Forbidden, 404 NotFound

POST /api/v1/search/reindex

Backfill the compact task search index for the authenticated API-key user

Responses: 200 Reindex result, 401 Unauthorized