API reference
2 endpoints, served at https://orbitwrite.com/api/v1. Each one lists the credentials it accepts, its parameters and every response it can give.
One read for a weekly check-in: the posting streak, each of the next days days (posts against the workspace's posting slots, so empty slots and empty days show), and what's stuck — posts awaiting approval and for how long, changes requested, failed publishes from the last two weeks, and drafts never given a time, oldest first. Lists carry up to five items and a total. Requires post:read; the streak needs analytics:read, the slots postingSchedule:read and account:read, and the approval lists approval:read — each is null without them. Contains no best-time heuristics.
An API key or OAuth access token as a bearer token, or a signed-in session.
organizationIdstringSession callers only — an API key already determines the workspace.
At least 1 character.
daysintegerDays to lay out, starting today. Defaults to 7.
Between 1 and 14.
weekStartsOninteger | nullFirst day of the week for the streak, as a getDay() index (0=Sun, 1=Mon, 6=Sat). Defaults to Monday.
200WeekOverviewThe week overview
timezonestringRequiredgeneratedAtstringRequiredstreakobject | any | nullRequiredNull without analytics:read.
currentintegerRequiredlongestintegerRequiredstatestringRequired"new""active""at_risk""broken"currentWeekSatisfiedbooleanRequiredwillExtendStreakbooleanRequiredweekEndsAtstringRequiredlastPostAtstring | any | nullRequirednextMilestoneobject | any | nullRequireddaysobject[]RequireddatestringRequired"YYYY-MM-DD" in the workspace timezone.
startsAtstringRequiredpostsWeekOverviewPost[]RequiredgroupIdstringRequiredtitlestring | any | nullRequiredexcerptstringRequiredThe first ~140 characters of the copy.
scheduledAtstring | any | nullRequiredbucketstringRequiredThe board column the post sits in.
slotsobject[] | any | nullRequiredThe day's posting slots, with the calendar's inheritance and occupancy rules. Null without postingSchedule:read and account:read.
openSlotsinteger | any | nullRequiredawaitingApprovalobject | any | nullRequiredOldest first. Null without approval:read.
totalintegerRequireditemsWeekOverviewWaiting[]RequiredgroupIdstringRequiredtitlestring | any | nullRequiredexcerptstringRequiredThe first ~140 characters of the copy.
scheduledAtstring | any | nullRequiredbucketstringRequiredThe board column the post sits in.
sincestringRequiredWhen the request was raised (awaiting approval) or answered (changes requested).
waitingDaysintegerRequiredreviewersstring[]RequiredReviewers yet to answer (awaiting approval), or who asked for changes.
dueDatestring | any | nullRequiredchangesRequestedobject | any | nullRequiredOldest first. Null without approval:read.
totalintegerRequireditemsWeekOverviewWaiting[]RequiredgroupIdstringRequiredtitlestring | any | nullRequiredexcerptstringRequiredThe first ~140 characters of the copy.
scheduledAtstring | any | nullRequiredbucketstringRequiredThe board column the post sits in.
sincestringRequiredWhen the request was raised (awaiting approval) or answered (changes requested).
waitingDaysintegerRequiredreviewersstring[]RequiredReviewers yet to answer (awaiting approval), or who asked for changes.
dueDatestring | any | nullRequiredfailedobjectRequiredcurl -X GET "https://orbitwrite.com/api/v1/week-overview" \
-H "Authorization: Bearer $ORBITWRITE_API_KEY"{
"timezone": "string",
"generatedAt": "string",
"range": {
"from": "string",
"to": "string"
},
"streak": {
"current": 0,
"longest": 0,
"state": "new",
"currentWeekSatisfied": true,
"willExtendStreak": true,
"weekEndsAt": "string",
"lastPostAt": "string",
"nextMilestone": {
"weeks": 0,
"label": "string"
}
},
"days": [
{
"date": "string",
"startsAt": "string",
"posts": [
{
"groupId": "string",
"title": "string",
"excerpt": "string",
"channels": [
{
"platform": "string",
"name": "string"
}
],
"scheduledAt": "string",
"bucket": "string"
}
],
"slots": [
{
"at": "string",
"filled": true,
"past": true
}
],
"openSlots": 0
}
],
"awaitingApproval": {
"total": 0,
"items": [
{
"groupId": "string",
"title": "string",
"excerpt": "string",
"channels": [
{
"platform": "string",
"name": "string"
}
],
"scheduledAt": "string",
"bucket": "string",
"since": "string",
"waitingDays": 0,
"reviewers": [
"string"
],
"dueDate": "string"
}
]
},
"changesRequested": {
"total": 0,
"items": [
{
"groupId": "string",
"title": "string",
"excerpt": "string",
"channels": [
{
"platform": "string",
"name": "string"
}
],
"scheduledAt": "string",
"bucket": "string",
"since": "string",
"waitingDays": 0,
"reviewers": [
"string"
],
"dueDate": "string"
}
]
},
"failed": {
"total": 0,
"items": [
{
"groupId": "string",
"title": "string",
"excerpt": "string",
"channels": [
{
"platform": "string",
"name": "string"
}
],
"scheduledAt": "string",
"bucket": "string",
"failedAt": "string",
"errors": [
{
"platform": "string",
"error": "string"
}
]
}
]
},
"drafts": {
"total": 0,
"items": [
{
"groupId": "string",
"title": "string",
"excerpt": "string",
"channels": [
{
"platform": "string",
"name": "string"
}
],
"scheduledAt": "string",
"bucket": "string",
"createdAt": "string",
"ready": true
}
],
"ready": 0
}
}The weekly digest: last week (or the week containing week) against the week before — posts published, impressions, engagements and link clicks received, follower change, the best post and the strongest pattern of the last four weeks — plus the week overview for the seven days from today. Requires post:read; the analytics half needs analytics:read and is null without it, and the week ahead degrades as GET /week-overview does.
An API key or OAuth access token as a bearer token, or a signed-in session.
organizationIdstringSession callers only — an API key already determines the workspace.
At least 1 character.
weekstringAny day of the week to report, YYYY-MM-DD in the workspace timezone. Defaults to the last complete week.
Matches ^\d{4}-\d{2}-\d{2}$.
weekStartsOninteger | nullFirst day of the week as a getDay() index (0=Sun, 1=Mon, 6=Sat). Defaults to Monday.
016200WeeklyDigestThe weekly digest
timezonestringRequiredgeneratedAtstringRequiredweekobjectRequiredpreviousWeekobjectRequiredcompletebooleanRequiredThe week has ended. False when the current week is asked for.
analyticsobject | any | nullRequiredNull without analytics:read.
historyDaysinteger | any | nullRequiredThe plan's analytics history in days when it cut the week short, else null.
postsobjectRequiredPosts published, counted as the posting streak counts them.
currentintegerRequiredpreviousinteger | any | nullRequiredchangePercentnumber | any | nullRequiredmetricsobject[]RequiredImpressions, engagements and link clicks *received* during the week, by posts of any age. A metric that moved in neither week is left out.
metricstringRequired"impressions""engagements""clicks"labelstringRequiredvaluenumberRequiredpreviousnumber | any | nullRequiredNull when the plan's history doesn't reach the week before.
changePercentnumber | any | nullRequiredfollowersobject | any | nullRequiredBiggest movers first. Null when no channel has a reading in the week.
topPostobject | any | nullRequiredThe post published in the week with the most engagement.
groupIdstring | any | nullRequiredpostIdsstring[]RequiredtextstringRequiredpublishedAtstringRequiredchannelsobject[]RequiredaccountIdstringRequiredplatformstringRequiredchannelstring | any | nullRequiredplatformUrlstring | any | nullRequiredmediaobject | any | nullRequiredThe post's first attachment, for a thumbnail, and how many it has. Null without media.
valuenumberRequiredThe ranked metric, summed over the post's channels.
metricsAnalyticsMetricValuesRequiredEach metric summed; null where nothing reported it (Bluesky has no impressions, say), never 0 for 'unknown'.
engagementsnumber | any | nullRequiredimpressionsnumber | any | nullRequiredreactionsnumber | any | nullRequiredcommentsnumber | any | nullRequiredrepostsnumber | any | nullRequiredquotesnumber | any | nullRequiredsavesnumber | any | nullRequiredclicksnumber | any | nullRequiredprofileClicksnumber | any | nullRequiredvideoViewsnumber | any | nullRequiredinsightobject | any | nullRequiredThe strongest pattern over the four weeks to the week's end.
idstringRequireddimensionstringRequiredWhat the posts were grouped by: format, topic (what the post is about: announcement, tutorial, event, case study, …), sentiment (its tone), hook (opening-line length), length, day, time (of day), link, hashtags, question, or tag.
"format""topic""sentiment""hook""length""day""time""link""hashtags""question""tag"groupstringRequiredThe group within the dimension: a format, a bucket, a weekday (0 = Sunday), a tag id, or yes.
directionstringRequired"better""worse"metricstringRequired"impressions""engagements"titlestringRequiredsummarystringRequiredOne sentence with the numbers.
liftnumberRequiredThe group's average against the rest's, each post measured against its channel's median: 2 is twice as well, 0.5 half.
postsintegerRequiredcomparedPostsintegerRequiredconfidencestringRequired"low""medium""high"exampleGroupIdsstring[]RequiredUp to three of the group's posts that show it best.
aheadWeekOverviewRequiredtimezonestringRequiredgeneratedAtstringRequiredstreakobject | any | nullRequiredNull without analytics:read.
currentintegerRequiredlongestintegerRequiredstatestringRequired"new""active""at_risk""broken"currentWeekSatisfiedbooleanRequiredwillExtendStreakbooleanRequiredweekEndsAtstringRequiredlastPostAtstring | any | nullRequirednextMilestoneobject | any | nullRequireddaysobject[]RequireddatestringRequired"YYYY-MM-DD" in the workspace timezone.
startsAtstringRequiredpostsWeekOverviewPost[]RequiredgroupIdstringRequiredtitlestring | any | nullRequiredexcerptstringRequiredThe first ~140 characters of the copy.
scheduledAtstring | any | nullRequiredbucketstringRequiredThe board column the post sits in.
slotsobject[] | any | nullRequiredThe day's posting slots, with the calendar's inheritance and occupancy rules. Null without postingSchedule:read and account:read.
openSlotsinteger | any | nullRequiredawaitingApprovalobject | any | nullRequiredOldest first. Null without approval:read.
totalintegerRequireditemsWeekOverviewWaiting[]RequiredgroupIdstringRequiredtitlestring | any | nullRequiredexcerptstringRequiredThe first ~140 characters of the copy.
scheduledAtstring | any | nullRequiredbucketstringRequiredThe board column the post sits in.
sincestringRequiredWhen the request was raised (awaiting approval) or answered (changes requested).
waitingDaysintegerRequiredreviewersstring[]RequiredReviewers yet to answer (awaiting approval), or who asked for changes.
dueDatestring | any | nullRequiredchangesRequestedobject | any | nullRequiredOldest first. Null without approval:read.
totalintegerRequireditemsWeekOverviewWaiting[]RequiredgroupIdstringRequiredtitlestring | any | nullRequiredexcerptstringRequiredThe first ~140 characters of the copy.
scheduledAtstring | any | nullRequiredbucketstringRequiredThe board column the post sits in.
sincestringRequiredWhen the request was raised (awaiting approval) or answered (changes requested).
waitingDaysintegerRequiredreviewersstring[]RequiredReviewers yet to answer (awaiting approval), or who asked for changes.
dueDatestring | any | nullRequiredfailedobjectRequiredcurl -X GET "https://orbitwrite.com/api/v1/weekly-digest" \
-H "Authorization: Bearer $ORBITWRITE_API_KEY"{
"timezone": "string",
"generatedAt": "string",
"week": {
"start": "string",
"end": "string",
"from": "string",
"to": "string"
},
"previousWeek": {
"start": "string",
"end": "string",
"from": "string",
"to": "string"
},
"complete": true,
"analytics": {
"historyDays": 0,
"posts": {
"current": 0,
"previous": 0,
"changePercent": 0
},
"metrics": [
{
"metric": "impressions",
"label": "string",
"value": 0,
"previous": 0,
"changePercent": 0
}
],
"followers": {
"total": 0,
"change": 0,
"channels": [
{
"accountId": "string",
"platform": "string",
"channel": "string",
"followers": 0,
"change": 0
}
]
},
"topPost": {
"groupId": "string",
"postIds": [
"string"
],
"text": "string",
"publishedAt": "string",
"channels": [
{
"accountId": "string",
"platform": "string",
"channel": "string",
"platformUrl": "string"
}
],
"media": {
"url": "string",
"mimeType": "string",
"count": 0
},
"tags": [
{
"id": "string",
"name": "string",
"color": "string"
}
],
"value": 0,
"metrics": {
"engagements": 0,
"impressions": 0,
"reactions": 0,
"comments": 0,
"reposts": 0,
"quotes": 0,
"saves": 0,
"clicks": 0,
"profileClicks": 0,
"videoViews": 0
}
},
"insight": {
"id": "string",
"dimension": "format",
"group": "string",
"direction": "better",
"metric": "impressions",
"title": "string",
"summary": "string",
"lift": 0,
"posts": 0,
"comparedPosts": 0,
"confidence": "low",
"exampleGroupIds": [
"string"
]
}
},
"ahead": {
"timezone": "string",
"generatedAt": "string",
"range": {
"from": "string",
"to": "string"
},
"streak": {
"current": 0,
"longest": 0,
"state": "new",
"currentWeekSatisfied": true,
"willExtendStreak": true,
"weekEndsAt": "string",
"lastPostAt": "string",
"nextMilestone": {
"weeks": 0,
"label": "string"
}
},
"days": [
{
"date": "string",
"startsAt": "string",
"posts": [
{
"groupId": "string",
"title": "string",
"excerpt": "string",
"channels": [
{
"platform": "string"
}
],
"scheduledAt": "string",
"bucket": "string"
}
],
"slots": [
{
"at": "string",
"filled": true,
"past": true
}
],
"openSlots": 0
}
],
"awaitingApproval": {
"total": 0,
"items": [
{
"groupId": "string",
"title": "string",
"excerpt": "string",
"channels": [
{
"platform": "string"
}
],
"scheduledAt": "string",
"bucket": "string",
"since": "string",
"waitingDays": 0,
"reviewers": [
"string"
],
"dueDate": "string"
}
]
},
"changesRequested": {
"total": 0,
"items": [
{
"groupId": "string",
"title": "string",
"excerpt": "string",
"channels": [
{
"platform": "string"
}
],
"scheduledAt": "string",
"bucket": "string",
"since": "string",
"waitingDays": 0,
"reviewers": [
"string"
],
"dueDate": "string"
}
]
},
"failed": {
"total": 0,
"items": [
{
"groupId": "string",
"title": "string",
"excerpt": "string",
"channels": [
{
"platform": "string",
"name": "string"
}
],
"scheduledAt": "string",
"bucket": "string",
"failedAt": "string",
"errors": [
{
"platform": "string",
"error": "string"
}
]
}
]
},
"drafts": {
"total": 0,
"items": [
{
"groupId": "string",
"title": "string",
"excerpt": "string",
"channels": [
{
"platform": "string",
"name": "string"
}
],
"scheduledAt": "string",
"bucket": "string",
"createdAt": "string",
"ready": true
}
],
"ready": 0
}
}
}