popkitpopkitAPI
中EN
Idea board

Create an idea

Add an idea to the board; no external side effects. It is attributed as agent output and shows up on the planning page for people to refine. Repeating a call with the same Idempotency-Key creates it once.

POST/api/v1/ideas
ideas:writewrite tierIdempotency-Key optional

Authorization & guardrails

  • Send Authorization: Bearer <credential>; credentials are issued under Settings → Integrations → Long-lived credentials, see Authentication.
  • The credential needs scope ideas:write; the issuer's workspace role must also allow the action.
  • Rate limit: write tier, 10/min per credential; over the cap returns 429 with Retry-After.
  • Idempotency: honoured when Idempotency-Key is present; optional otherwise.

Request body (application/json)

contentstringrequired

Idea text.

groupIdstringoptional

Target group; omit for the default group.

tagsobject[] { label, color? }optional

Up to 6 hashtags, added to the start of the post when the idea is turned into a draft. Don't use them to track progress (planned / scheduled / posted…); the system tracks that. color is a palette key (violet / blue / teal / green / …), defaulting when omitted.

imagestring (URL)optional

Image URL.

plannedAtdatetime (ISO 8601)optional

Carried over as the draft's scheduled time when the idea is converted (editable afterwards in the composer). It never publishes on its own and is not shown on the idea board. Omit for none.

targetAccountIdsstring[]optional

Pre-selected target accounts.

clientRequestIdstringoptional

Idempotency key (8–128 chars of [A-Za-z0-9_.:-]); prefer the Idempotency-Key header, which wins over the body.

Responses

Success is HTTP 201 with a { data, meta } envelope; examples per status are on the right (at the end of the page on narrow screens). Every error is { error: { code, message, params }, meta } — branch on the code, not the message; see Errors.

StatusPossible codes
400invalid_input
401unauthenticated
402plan_limit
403forbidden / workspace_not_found
404not_found
409no_account / needs_reauth / replay
429rate_limited
500internal
502platform_error
503external_writes_off

Examples

Request
curl -X POST "https://popkit.loxily.com/api/v1/ideas" \
  -H "Authorization: Bearer popkit_it_••••••••" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-2026-09-21-001" \
  -d '{
  "content": "国庆档「一次创作,多平台发布」教程短视频",
  "tags": [
    {
      "label": "教程",
      "color": "blue"
    }
  ],
  "plannedAt": "2026-09-28T10:00:00+08:00"
}'
Response
Created
{
  "data": {
    "id": "ide_01J8ZS…",
    "groupId": "idg_01J8…",
    "deepLink": "https://popkit.loxily.com/planning?idea=ide_01J8ZS…"
  },
  "meta": {
    "requestId": "6a1d0c9e-2b7f-4e3a-8c5d-1f0e9b8a7c79"
  }
}
MCP docs