Skip to main content
Developers

REST API

Authenticate with an API key and manage posts, media, campaigns, calendar and analytics from code.

Authentication

Create a personal API key under Developers (or Settings). Send it as a bearer token. The same ppk_... keys also work for the MCP server.

http
Authorization: Bearer ppk_xxxxxxxxxxxxxxxx

Base URL: https://plotpostapi.kriva.studio. Bodies are JSON; timestamps are ISO-8601 in UTC. Keys are shown once and only a hash is stored, so keep them secret.

What a key can do

  • A key acts as its owner. The owner’s role in each workspace decides what is allowed (403 without permission, 404 for workspaces the owner does not belong to).
  • A key can be restricted to some workspaces when it is created.
  • Reachable: /api/posts, /api/media, /api/campaigns, GET /api/calendar, GET /api/analytics/*, read-only account routes and GET /api/applications.
  • Never reachable (403 API_KEY_FORBIDDEN): sign-in, billing, team, credentials, connecting or removing accounts, key management, webhooks, data export.

Rate limits

Defaults per key: 120 requests per minute and 90 post creations per hour (re-queues included). Exceeding them returns 429 RATE_LIMITED.

Examples

List workspaces and accounts
API=https://plotpostapi.kriva.studio
KEY=ppk_your_key_here

curl -s "$API/api/applications" -H "Authorization: Bearer $KEY"
curl -s "$API/api/accounts?application_id=WORKSPACE_ID" -H "Authorization: Bearer $KEY"
Schedule a post (09:30 IST = 04:00 UTC)
curl -s -X POST "$API/api/posts" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{
  "application_id": "WORKSPACE_ID",
  "body": "Hello from the API",
  "account_ids": ["ACCOUNT_ID_1", "ACCOUNT_ID_2"],
  "content_overrides": { "ACCOUNT_ID_2": "Shorter text for this channel" },
  "action": "schedule",
  "scheduled_for": "2026-11-02T04:00:00Z"
}'
Create a draft
curl -s -X POST "$API/api/posts" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"application_id":"WORKSPACE_ID","body":"Draft text","account_ids":["ACCOUNT_ID_1"],"action":"draft"}'
Read, edit, delete
curl -s "$API/api/posts?application_id=WORKSPACE_ID&status=scheduled" -H "Authorization: Bearer $KEY"
curl -s "$API/api/posts/POST_ID" -H "Authorization: Bearer $KEY"
curl -s -X PATCH "$API/api/posts/POST_ID" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"body":"Edited"}'
curl -s -X DELETE "$API/api/posts/POST_ID" -H "Authorization: Bearer $KEY"
Upload media, then attach it
curl -s -X POST "$API/api/media" -H "Authorization: Bearer $KEY" \
  -F "application_id=WORKSPACE_ID" -F "file=@./photo.jpg"
# then use the returned id in "media_ids": ["..."] when creating a post
Next free slot, re-queue and repeat
curl -s "$API/api/accounts/ACCOUNT_ID/next-slot" -H "Authorization: Bearer $KEY"
curl -s -X POST "$API/api/posts/POST_ID/requeue" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"use_next_slot": true, "repeat": {"every_days": 30, "max_occurrences": 4}}'
Calendar and analytics
curl -s "$API/api/calendar?from=2026-11-01T00:00:00Z&to=2026-12-01T00:00:00Z" -H "Authorization: Bearer $KEY"
curl -s "$API/api/analytics/overview?range=30d" -H "Authorization: Bearer $KEY"
curl -s "$API/api/analytics/export.csv?workspace_id=WORKSPACE_ID" -H "Authorization: Bearer $KEY" -o report.csv

Errors

Errors always have the same shape:

json
{ "error": { "code": "RATE_LIMITED", "message": "Too many requests" } }
StatusMeaning
400Invalid input or a platform rule would be broken.
401Missing or invalid API key.
403Your role does not allow this, or the route is not available to keys.
404Not found, or a workspace you do not belong to.
409Conflict, for example an expired account that needs reconnecting.
429Rate limit reached.

v0.1.2

REST API | Documentation | Sociquza