Create a document body

POSThttps://<your-url>/api/v2/drive-documents

MCP id drive-documents.storeAlso on this path: GET List document bodies

Gives an existing bodyless drive item a body, and returns it with a Location header.

Token scope: api:write:project_driveorapi:write:customer_driveorapi:write:organization_driveorapi:write:user_drive
Without it: 403 insufficient-token-scope.
Permission: project_drive::create
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 body for a freshly created drive item

curl -X POST \
  'https://<your-url>/api/v2/drive-documents' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <key>' \
  -d '{
    "drive_item_id": 1,
    "content": "# Kick-off\n\n- [ ] Confirm scope with the client\n- [x] Book the room\n"
  }'

const response = await fetch('https://<your-url>/api/v2/drive-documents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '<key>',
  },
  body: JSON.stringify({
    "drive_item_id": 1,
    "content": "# Kick-off\n\n- [ ] Confirm scope with the client\n- [x] Book the room\n"
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', '<key>')
    ->post('https://<your-url>/api/v2/drive-documents', [
        'drive_item_id' => 1,
        'content' => '# Kick-off

- [ ] Confirm scope with the client
- [x] Book the room
',
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/drive-documents',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': '<key>'},
    json={'drive_item_id': 1, 'content': '# Kick-off

- [ ] Confirm scope with the client
- [x] Book the room
'},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "drive_item_id": 1,
    "content": "# Kick-off\n\n- [ ] Confirm scope with the client\n- [x] Book the room\n",
    "content_html": "<p>…</p>",
    "created_at": "2026-03-04T09:15:00Z",
    "updated_at": "2026-03-04T09:15:00Z",
    "links": {
      "self": "https://<your-url>/api/v2/work-items/1"
    }
  }
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/duplicate-resource",
  "title": "Duplicate resource",
  "status": 409,
  "detail": "Another project already uses the code \"ACM\".",
  "instance": "/api/v2/projects",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "conflict": {
    "field": "code",
    "value": "ACM"
  }
}

{
  "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."
    }
  ]
}

This is the second half of creating a document: POST /api/v2/drive-items creates the item, and this endpoint fills it in. content is GitHub-Flavored Markdown and may be omitted for an empty document. Two refusals: an item that already has a body answers 409 duplicate-resource, because a drive item has at most one, and an item that is not an editable document (an uploaded PDF, image or Office file) answers 422 on /drive_item_id, since there is no editor schema to hold a body. An item the caller cannot read is refused exactly as a nonexistent one is. Because the body did not exist a moment ago, no collaboration room can be open on it, so the content is stored directly and the editor adopts it on first open. The declared permission is project_drive::create; the other three drive prefixes apply by the owning item's owner type, and the record rule, edit access on that item, is what actually decides.

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 this body belongs to. Set on create and immutable afterwards; read the item itself from GET /api/v2/drive-items/{drive_item}.

contentstring or null≤ 262144

The document body as GitHub-Flavored Markdown: headings, lists, task lists (- [ ]), tables, code fences, links and images all survive. Detail-only: pass ?view=detail to get it on the collection. Markdown cannot express text colours, highlights, alignment or @mentions, so read ?include=content_html first if the document may contain them: a read of content followed by a PATCH of it discards all four permanently.

Response 201

Returns a DriveDocument 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