Introduction

Postey.ai exposes a REST API to manage posts, schedules, approvals, and accounts, enabling custom tooling and integrations on top of the creator workspace. This guide sets up authentication, makes a first request, and explains pagination, errors, and limits to build reliable clients.

Base URL

• Production: https://srvr.postey.ai/v1
• All requests must use HTTPS. Versioning via the /v1 path helps maintain backward compatibility across releases.

Authentication

• Scheme: Bearer token via the Authorization header.
• Header format: Authorization: Bearer <access_token>
• Keep tokens secret, store in environment variables or a vault, and rotate regularly.

Your first request

• Endpoint: GET /posts — returns a paginated list of posts.
• cURL:

curl -s -H "Authorization: Bearer $POSTEY_TOKEN" "https://srvr.postey.ai/v1/posts?per_page=10&page=1&status=published"[1]

• JavaScript (fetch):
  • const res = await fetch("https://srvr.postey.ai/v1/posts?per_page=10&page=1", { headers: { Authorization: Bearer ${process.env.POSTEY_TOKEN} } }); const data = await res.json(); console.log(data);
• Python (requests):
  • import os, requests; r = requests.get("https://srvr.postey.ai/v1/posts", params={"per_page":10,"page":1}, headers={"Authorization": f"Bearer {os.getenv('POSTEY_TOKEN')}" }); print(r.json())

Errors

• 400 Bad Request — invalid parameters.
• 401 Unauthorized — missing/invalid token.
• 403 Forbidden — lack of permission.
• 404 Not Found — missing route/resource.
• 429 Too Many Requests — rate limit exceeded.
• 5xx Server Error — transient failure; implement retries with backoff.

Rate limits

• On 429, respect Retry-After (seconds) if present and back off with jitter; cache GET responses where possible to reduce calls.
• Design clients to stay within limits by batching requests and using appropriate per_page sizes.

Security best practices

• Don’t commit tokens to source control; use environment variables and CI secrets.
• Prefer short-lived tokens and rotate on compromise; scope to least privilege.