pixPLace API for developers and AI agents

1. Get a key

Sign in to pixPLace, open Settings → Developer and press New Key. The full key is shown once: store it as a secret (an n8n credential, an environment variable). Up to 3 keys per account; revoke a key there at any time. A key never leaves its account: it cannot act for another one.

2. Upload a file

Media must be on a host the portal can render. The simplest way: let the server download a public URL with POST /api/v1/uploads/from-url. The answer holds data.publicUrl on cdn.pixplace.space. (Videos up to 200 MB: POST /api/v1/uploads, a presigned PUT.)

curl -X POST https://pixplace.space/api/v1/uploads/from-url \
  -H "Authorization: Bearer ppk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: upload-exec-1001-item-0" \
  -d '{
  "url": "https://example.com/photos/living-room.jpg"
}'

3. Create the post

POST /api/v1/posts with the publicUrl as attachments[].url. The same Idempotency-Key on a retry returns the original post instead of a duplicate (HTTP 200 and Idempotent-Replayed: true). The answer has the post url.

curl -X POST https://pixplace.space/api/v1/posts \
  -H "Authorization: Bearer ppk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-post-1" \
  -d '{
  "title": "Minimalist living room",
  "attachments": [
    {
      "url": "https://cdn.pixplace.space/content/cm9x2k4ab0001ld0h5q7w3e2z/2026-10/3f1c2a9e-5b7d-4c11-9a7e-0b1c2d3e4f5a.jpg",
      "type": "IMAGE",
      "width": 1536,
      "height": 1024,
      "altText": "Bright minimalist living room with an oak table"
    }
  ],
  "description": "AI-generated interior concept",
  "tags": [
    "interior",
    "minimal"
  ]
}'

Optional: a story

The same publicUrl works for a story that disappears after 24 hours: POST /api/v1/stories with url and type.

curl -X POST https://pixplace.space/api/v1/stories \
  -H "Authorization: Bearer ppk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: exec-1001-story-0" \
  -d '{
  "url": "https://cdn.pixplace.space/content/cm9x2k4ab0001ld0h5q7w3e2z/2026-10/3f1c2a9e-5b7d-4c11-9a7e-0b1c2d3e4f5a.jpg",
  "type": "IMAGE"
}'

n8n: three HTTP Request nodes

Create one Header Auth credential (Name Authorization, Value Bearer ppk_live_…) and use it in all nodes. Turn Retry On Fail on (3 tries, 5000 ms): the Idempotency-Key makes the repeat safe.

1. Node 1 — Upload from URL. Method / URL: POST https://pixplace.space/api/v1/uploads/from-url. Body (JSON, expression): {{ JSON.stringify({ url: $json.imageUrl }) }}. Header Idempotency-Key: upload-{{ $execution.id }}-{{ $itemIndex }}.
2. Node 2 — Create post. POST https://pixplace.space/api/v1/posts, header Idempotency-Key: post-{{ $execution.id }}-{{ $itemIndex }}. Connect it directly after node 1; the body takes publicUrl from node 1:

{{ JSON.stringify({
  title: $('Source item').item.json.title,
  attachments: [{ url: $json.data.publicUrl, type: $json.data.type }],
  description: $('Source item').item.json.description
}) }}

Node 3 (optional) — Create story. POST https://pixplace.space/api/v1/stories, header Idempotency-Key: story-{{ $execution.id }}-{{ $itemIndex }}, body:

{{ JSON.stringify({ url: $('Upload from URL').item.json.data.publicUrl, type: $('Upload from URL').item.json.data.type }) }}

To see a 429 in the workflow instead of an error, set Options → Response → Include Response Headers and Status and Never Error, then wait {{ $json.headers["retry-after"] }} seconds before the retry.

AI agent: copy this prompt

Give it to your agent (Claude, ChatGPT, a custom tool-calling bot) together with the key as a secret. The agent reads the spec itself: every operation, field, limit and error is in https://pixplace.space/api/v1/openapi.json.

Use the OpenAPI spec at https://pixplace.space/api/v1/openapi.json to call the pixPLace API.
Authenticate every request except GET /api/v1/categories and GET /api/v1/niches with the header
"Authorization: Bearer <PIXPLACE_API_KEY>" (a ppk_live_… key from Settings → Developer; never print or log it).
To publish: upload each file with POST /api/v1/uploads/from-url, then create the post with POST /api/v1/posts,
using data.publicUrl as attachments[].url and its type as attachments[].type.
Send an Idempotency-Key header on every create call and REUSE the same key when you retry.
On 429 or 503 wait the number of seconds in the Retry-After header before retrying; on 400 fix the request, do not retry it.
Before you promise a metric or action, check x-unavailable in the spec: what is listed there does not exist.

Idempotency-Key

• Accepted by POST /api/v1/posts, POST /api/v1/stories and POST /api/v1/uploads/from-url. 1–128 characters from A–Z a–z 0–9 . _ : - ; anything else is a 400.
• A repeat from the same account returns the ORIGINAL result with HTTP 200 and the header Idempotent-Replayed: true; a first success is 201. A replay spends no quota.
• Retry a 429, a 503 or a timeout with the SAME key. For a new item use a new key. In n8n: {{ $execution.id }}-{{ $itemIndex }}.
• POST /api/v1/posts/{id}/comments has NO idempotency: a repeat creates a duplicate comment. After a timeout read the list first.

• Views, saves and deeplink clicks: the platform does not collect them, so /stats cannot report them (the response says so in `unavailable` instead of returning zeros).
• Account-level views, saves, deeplink clicks and profile views: not collected either, so /account/stats lists them in `unavailable` and has no numbers for them.
• Per-day shares: shares are only a running total.
• Hiding comments (keeping them but not showing them): not available yet — a hidden flag needs a new column and comes in a later phase. For now the only moderation is deleting a comment.
• Editing a comment, reactions to comments and a count of reactions by kind: not available through the API.
• Filtering comments by author or text, or reading them newest first for a single post: not available. The inbox (GET /comments) is the newest-first view across all your posts.
• One key for several accounts: a key always acts for its one owner. Managing several accounts with one key is planned for later.
• Changing the media of a post: delete the post and create a new one.
• Following or unfollowing, removing a follower, blocking: followers and following are read-only. Notifications are read-only too, apart from marking them as read; there is no deleting them.
• MCP: the Social API is REST only. There are no MCP tools for these endpoints; use HTTP with the API key (n8n HTTP Request node, curl).
• Statistics per country, device or traffic source, and anything older than 90 days in one request: not available (ask for several ranges).
• Notifying the author of a comment you reply to: the site does not do it either.