Create a todo

POSThttps://<your-url>/api/v2/todos

MCP id todos.storeAlso on this path: GET List your todos

Creates a todo for you against a drive item and returns it with a Location header.

Token scope: api:write:project_management
Without it: 403 insufficient-token-scope.
Permission: project_management::manage_work_items
Without it: 403 insufficient-permission.
Rate cost: 1 unit, write bucket. A write costs the same whatever view you ask for.
Also: Accepts Idempotency-Key. Never cached: private, no-store. Unknown body keys are refused, never dropped.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: A todo against a document

curl -X POST \
  'https://<your-url>/api/v2/todos' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <key>' \
  -d '{
    "drive_item_id": 1,
    "todo_content": "Confirm the kick-off date with the client"
  }'

const response = await fetch('https://<your-url>/api/v2/todos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '<key>',
  },
  body: JSON.stringify({
    "drive_item_id": 1,
    "todo_content": "Confirm the kick-off date with the client"
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', '<key>')
    ->post('https://<your-url>/api/v2/todos', [
        'drive_item_id' => 1,
        'todo_content' => 'Confirm the kick-off date with the client',
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/todos',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': '<key>'},
    json={'drive_item_id': 1, 'todo_content': 'Confirm the kick-off date with the client'},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "user_id": 1,
    "drive_item_id": 1,
    "todo_content": "Confirm the kick-off date with the client",
    "created_at": "2026-03-04T09:15:00Z",
    "updated_at": "2026-03-04T09:15:00Z",
    "user": {
      "id": 1
    },
    "links": {
      "self": "https://<your-url>/api/v2/work-items/1"
    }
  }
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/idempotency-key-in-flight",
  "title": "Idempotency key in flight",
  "status": 409,
  "detail": "The original request for this Idempotency-Key is still being processed. Retry shortly.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S"
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "3 fields failed validation.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "errors": [
    {
      "pointer": "/date",
      "code": "date_format",
      "detail": "The date does not match the format Y-m-d."
    },
    {
      "pointer": "/minutes",
      "code": "min",
      "detail": "The minutes must be at least 1."
    },
    {
      "pointer": "/description",
      "code": "required",
      "detail": "The description field is required."
    }
  ]
}

user_id is always the authenticated caller and cannot be set: there is no way to create a todo for someone else. A drive item you cannot read, or one that is archived, is refused exactly as a nonexistent one is. ⚠ This write is temporary by construction. Todos are a derived copy of document content: the next write to the source drive item (including a title-only PATCH /api/v2/drive-items/{drive_item}) deletes every todo for that item and rebuilds the set from the document HTML, so a todo created here disappears the next time its document is touched. To create a todo that lasts, add an unchecked task item mentioning the user to the document itself.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

viewstring

Which field set to render.

summarydetaildefault

Request headers

X-Request-Idstringpattern

A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.

Idempotency-Keystring≤ 255

A caller-chosen key that makes this POST safe to retry. Replaying it returns the original response with Idempotency-Replayed: true.

Request body

Unknown keys are refused with 422, naming the key.

drive_item_idinteger → DriveItem.idRequired

The drive item whose document this todo was parsed out of. Writable on create only; a todo cannot be re-parented. No relation object is exposed for it; read the document with GET /api/v2/drive-items/{drive_item}, which applies the drive access rules this collection does not. Archiving a drive item leaves its todos behind, so this id can name an item you can no longer read.

todo_contentstring≤ 65535Required

The todo line as plain text.

Response 201

Returns a UserTodo in the detail view.

Headers

ETag: A strong validator of exactly this representation.
Idempotency-Replayed: true when this response was replayed from a stored Idempotency-Key rather than produced by a new write.
Location: The absolute URL of the created or queued resource.
RateLimit: The IETF httpapi-ratelimit-headers form of your remaining allowance on the tightest bucket this request touched.
RateLimit-Policy: The ceiling and window of that bucket, as <limit>;w=<seconds>.
X-Request-Id: The server-generated ULID correlating this response with our logs.

Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning