API Reference
Build on Oocta
A small REST API for creating and scheduling posts and pulling analytics programmatically — the same data your dashboard runs on. Available on the Scale plan.
Getting started
- 1. Generate a key from Settings → API keys in your dashboard. The raw key is shown once — copy it somewhere safe.
- 2. Send it as a Bearer token on every request.
- 3. Grant only the scopes a key actually needs — you choose them when you create it.
curl https://www.oocta.work/api/v1/posts \
-H "Authorization: Bearer oocta_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Base URL: https://www.oocta.work/api/v1. All requests and responses are JSON.
Authentication & scopes
Every key is scoped. A request fails with 403 if its key doesn't carry the scope an endpoint requires.
readList posts, pull analytics.writeCreate draft or scheduled posts.
The key creation form also offers publish and generate scopes for future endpoints — no current endpoint checks for them yet, so granting them today has no effect.
Endpoints
/postsscope: readList your posts, newest first.
Query parameters
statusstring, optionaldraft, scheduled, published, cancelled, or failed.limitinteger, optionalDefault 50, max 200. Non-numeric values fall back to the default.offsetinteger, optionalDefault 0, for pagination.
Request
curl "https://www.oocta.work/api/v1/posts?status=published&limit=20" \
-H "Authorization: Bearer oocta_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Response — 200
{
"posts": [
{
"id": "3fa6c9c0-...",
"content": "Shipping is a feature.",
"platforms": ["twitter", "linkedin"],
"status": "published",
"scheduled_for": null,
"published_at": "2026-09-10T14:02:11.000Z",
"created_at": "2026-09-10T13:58:44.000Z"
}
],
"pagination": { "limit": 20, "offset": 0 }
}/postsscope: writeCreate a draft, or schedule one for future publishing.
Body
contentstring, requiredUp to 10,000 characters.platformsstring[], requiredNon-empty subset of twitter, facebook, instagram, linkedin, tiktok, youtube, threads.scheduled_forISO date, optionalMust be in the future. Omit to create a draft instead of a scheduled post.
Request
curl -X POST https://www.oocta.work/api/v1/posts \
-H "Authorization: Bearer oocta_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"content": "New: scheduled posting via the API.",
"platforms": ["twitter", "linkedin"],
"scheduled_for": "2026-10-01T15:00:00.000Z"
}'Response — 201
{
"post": {
"id": "9a2e1b4d-...",
"content": "New: scheduled posting via the API.",
"platforms": ["twitter", "linkedin"],
"status": "scheduled",
"scheduled_for": "2026-10-01T15:00:00.000Z",
"created_at": "2026-09-16T10:00:00.000Z"
}
}If scheduled_for is set, the post is queued for automatic publishing at that time — same pipeline as scheduling from the dashboard. A 503 means the row was created but the scheduler couldn't be reached; the post is marked failed rather than left silently stuck.
/analyticsscope: readAggregated performance across a rolling window.
Query parameters
daysinteger, optionalDefault 30, clamped between 1 and 365.
Request
curl "https://www.oocta.work/api/v1/analytics?days=7" \
-H "Authorization: Bearer oocta_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Response — 200
{
"period": { "days": 7, "since": "2026-09-09T10:00:00.000Z" },
"totals": {
"posts_created": 12,
"posts_published": 9,
"likes": 431,
"comments": 58,
"shares": 22,
"impressions": 18420,
"engagement": 511
}
}Errors
Every error is { "error": "..." } with a status code that tells you what to do about it.
401Missing, malformed, or revoked/expired API key.403Key is valid but missing the scope the endpoint requires.400Request body or query params failed validation.500Something broke on our end. Safe to retry.503A scheduled post was created but couldn't be queued — check the post's status.