popkitpopkitAPI
中EN
Posts

List posts

Paginated list of drafts, scheduled and published posts (eight statuses). The cursor is opaque; pass back nextCursor to fetch the next page.

GET/api/v1/posts
posts:readread tierread-only

Authorization & guardrails

  • Send Authorization: Bearer <credential>; credentials are issued under Settings → Integrations → Long-lived credentials, see Authentication.
  • The credential needs scope posts:read; the issuer's workspace role must also allow the action.
  • Rate limit: read tier, 60/min per credential; over the cap returns 429 with Retry-After.
  • Idempotency: read endpoint, no Idempotency-Key needed.
  • Read-only: writes nothing and sends nothing out.

Query parameters

statusenum: draft · reviewing · approved · rejected · scheduled · publishing · published · failedoptional

Filter by status; omit for all.

platformenum: x · youtube · instagram · tiktok · facebook · threads · douyin · xiaohongshu · wechat_mpoptional

Filter by target platform.

limitinteger 1–100optional

Page size, default 20.

cursorstringoptional

nextCursor from the previous page.

Responses

Success is HTTP 200 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
403forbidden / workspace_not_found
404not_found
429rate_limited
500internal

Examples

Request
curl -X GET "https://popkit.loxily.com/api/v1/posts?status=scheduled&limit=20" \
  -H "Authorization: Bearer popkit_it_••••••••"
Response
OK
{
  "data": {
    "items": [
      {
        "id": "pst_01J8ZK3R7QW6M2",
        "title": null,
        "content": "新功能上线:一次创作,发布到所有平台 🚀",
        "platforms": [
          "x",
          "instagram"
        ],
        "targetAccountIds": [
          "acc_01J8X…",
          "acc_01J8Y…"
        ],
        "status": "scheduled",
        "source": "api",
        "scheduledAt": "2026-09-21T10:00:00.000Z",
        "publishedAt": null,
        "createdBy": "usr_01J7…",
        "createdAt": "2026-09-20T08:12:31.000Z",
        "updatedAt": "2026-09-20T08:12:31.000Z",
        "deepLink": "https://popkit.loxily.com/calendar?post=pst_01J8ZK3R7QW6M2"
      }
    ],
    "nextCursor": "eyJjIjoiMjAyNi0wOS0yMFQwODoxMjozMS4wMDBaIiwiaWQiOiJwc3RfMDFKOFpLM1I3UVc2TTIifQ"
  },
  "meta": {
    "requestId": "6a1d0c9e-2b7f-4e3a-8c5d-1f0e9b8a7c63"
  }
}
MCP docs