Documentation

API Reference

Use the PostPiper REST API to manage connected accounts, drafts, publishing, scheduling, and images.

Base URLhttps://api.postpiper.ai/v1

OpenAPIDownload the OpenAPI specification for API clients and AI agents.

AuthenticationBearer $POSTPIPER_API_KEYCreate an API key

Terminal

curl -H "Authorization: Bearer $POSTPIPER_API_KEY" \
  "https://api.postpiper.ai/v1/accounts"

Accounts

GETList Pinterest BoardsList public Boards owned by a connected Pinterest account./accounts/{accountId}/boardsGETList connected accountsPostPiper API: list active social accounts connected to your PostPiper user. Optionally filter by platform such as X, LinkedIn, or Pinterest./accounts

Posts

POSTCreate a draftPostPiper API: create an unpublished post draft with text and/or images for X, LinkedIn, or Pinterest. Draft creation does not publish the post./postsPATCHEdit a draftPostPiper API: update an existing draft's text, image attachments, or Pinterest fields. Only unpublished drafts can be edited with PATCH./posts/{postId}GETGet a postPostPiper API: read an owned post by ID, including content, media, platform, account, and current draft, scheduled, published, or failed status./posts/{postId}GETList postsPostPiper API: page through owned posts by status, platform, account, or time range. Supports cursor pagination, filters, and sort options./postsPOSTPublish a postPostPiper API: publish an X, LinkedIn, or Pinterest draft immediately to the connected account. No request body; returns updated post status./posts/{postId}/publishPOSTSchedule a postPostPiper API: schedule an owned X, LinkedIn, or Pinterest draft for a future time using ISO 8601 scheduled_at. Requires a connected account./posts/{postId}/schedule

Media

POSTUpload an imagePostPiper API: upload one JPEG, PNG, or WebP image as multipart form data. Returns an owned asset ID for use in X, LinkedIn, or Pinterest drafts./mediaPOSTImport an imagePostPiper API: import one publicly accessible HTTPS image into PostPiper media storage. Supports JPEG, PNG, or WebP images up to 5 MB./media/importGETList imagesPostPiper API: list your latest ready image assets, newest first. Each result includes mime type, size bytes, and a signed preview URL./mediaGETGet an imagePostPiper API: read owned image metadata and get a fresh preview URL. Signed preview links expire after 15 minutes—call again when needed./media/{assetId}

Errors

Use the HTTP status and error.code to handle failures; include request_id when contacting support.

Successful response · 200

Example from GET /accounts?platform=x.

JSON

{
  "accounts": [
    {
      "id": "<account-uuid>",
      "platform": "x",
      "platform_user_id": "123456789",
      "platform_username": "example",
      "platform_display_name": "Example",
      "platform_avatar_url": null
    }
  ]
}

Error response · 400

Example from an invalid platform query value.

JSON

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request validation failed",
    "request_id": "req-123"
  }
}

HTTP status and error codes

HTTP status	When it occurs	Example `error.code`
400	Invalid parameters or post content	`INVALID_REQUEST`, `INVALID_CONTENT`
401	Missing or invalid API key	`UNAUTHORIZED`
403	API key lacks the required scope	`FORBIDDEN`
404	Resource or route not found	`POST_NOT_FOUND`, `ROUTE_NOT_FOUND`
409	Post or upload is in the wrong state	`POST_NOT_DRAFT`
413 / 415	File too large / unsupported media type	`MEDIA_TOO_LARGE` / `INVALID_MEDIA_REQUEST`
429	Upload or platform rate limit	`MEDIA_RATE_LIMITED`, `X_RATE_LIMITED`
500 / 502 / 503	Server, upstream, or service failure	`INTERNAL_ERROR`, `X_PUBLISH_FAILED`, `SERVICE_UNAVAILABLE`