Scratchpad

Create scratchpad item

Drops a new note, link, or image/file into the org scratchpad.

POST/api/public/scratchpad
cURLPOST /api/public/scratchpad
curl -X POST https://postiv.ai/api/public/scratchpad \
  -H "Authorization: Bearer pk_postiv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "note",
    "content": "Three things we learned from launch week..."
  }'
200Response
{
  "success": true,
  "item": {
    "id": "sp2...",
    "kind": "url",
    "url": "https://example.com/article",
    "status": "fresh",
    "createdAt": "2026-07-19T09:00:00.000Z"
  }
}

Authorization

Requires an organization API key with the scratchpad:write scope, sent as Authorization: Bearer or x-api-key.

Body parameters

kindstringrequired
One of:noteurlimagefile
contentstring

Max 50000 chars. Required for kind=note; optional caption otherwise.

urlstring

Required for kind=url; server-side scrapes title/description/image.

imageUrlstring

For kind=image, fetched server-side (SSRF-guarded, size-capped) instead of s3Key.

s3Keystring

For kind=image or kind=file, from create-scratchpad-upload-url.

contentTypestring

Required with s3Key.

fileNamestring

Required for kind=file.

boardPositionobject

{ x, y }.

Response

The created item.

itemobject

Same shape as a list-scratchpad-items entry.

Errors

400invalid_kind: bad/missing kind or missing required field for that kind
422invalid_image: image fetch/validation failed

Good to know

  • Status is 201 Created. Always tagged source='mcp' internally regardless of REST vs. MCP origin, and attributed to the API key's actor.