API reference

1. Open your workspace

Independent hosting supports Google and Apple OAuth when the operator configures provider credentials, the authentication secret, domain and database migration. Apple appears on Apple devices and requires an HTTPS domain. Email sign-in uses a 6-digit code when Resend and a verified sender are configured. Codes expire after 10 minutes and allow five attempts. Missing configuration returns an unavailable error, not a session. Sign in before opening your workspace; API routes verify the session on the server. After authentication, new users enter their first and last name and optional company name, then select a trial plan. Connections are available in Settings. Invitations are available in Settings only for an active Team or Max trial or subscription. Completed profiles skip onboarding; Finish onboarding resumes an unfinished setup at its saved checkpoint. Stripe Checkout is test-mode only and requires operator configuration; card details stay on Stripe. A signed webhook confirms completion, not a redirect. Live billing is not enabled. Welcome step views and progress are recorded without form contents; local demo sessions are separated from live onboarding metrics. Setup completion is counted after the verified trial webhook or a separate local preview completion. Local development offers an isolated demo session without email verification. An explicitly configured Cloudflare preview also supports demo sessions on its exact preview host, with a separate database and no live service secrets. Standard production builds disable demos. A demo never signs in as the entered email. Local email sign-up previews a create-password step; the sample password is never transmitted or saved. Live email signup creates a password and verifies email with a code; sign-in supports passwords or email codes. Configure a verified sender before enabling email signup.

Sign in to Postii and keep its dashboard open. The examples below run in that page’s browser console, using your existing session. Requests are relative to this site; there is no separate API host or token to copy.

These are same-origin examples, not a server-to-server integration. Sandbox post storage is isolated by authenticated user; workspace_demo is a request alias, not a shared data store. Do not copy session cookies or identity headers into external tools.

2. Read capabilities

const response = await fetch('/api/v1/channels/capabilities', {
  credentials: 'same-origin'
});
if (!response.ok) throw new Error('Could not load capabilities');
const { data: platforms } = await response.json();
console.table(platforms.map(p => ({
  platform: p.provider,
  connected: p.availability.connected,
  mode: p.availability.mode
})));

This endpoint describes the social-post sandbox. beehiiv connection status has its own endpoint below. A listed platform or a saved schedule does not mean live delivery is enabled. Social Connect buttons currently show an unavailable error toast; they do not authorize or save an account. beehiiv uses its separate connection flow. Connection dialogs include account-selection reminders, but those reminders do not mean OAuth is active. Check the account handle and requested permissions before approving any future authorization.

3. Validate a post without saving

const response = await fetch('/api/v1/posts', {
  method: 'POST',
  credentials: 'same-origin',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    workspace_id: 'workspace_demo',
    content: 'A small update from our team.',
    channels: ['linkedin'],
    scheduled_at: new Date(Date.now() + 86400000).toISOString(),
    schedule_timezone: 'America/Toronto',
    dry_run: true
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.detail || 'Validation failed');
console.log(result);

To save a sandbox schedule, set dry_run: false and send an Idempotency-Key header. Generate a new key for a new operation; reuse the same key and identical body when retrying. Saved schedules and auto-DM rules do not deliver posts or messages.

Connect beehiiv

From the dashboard, choose Connect a platform or Platforms → Manage connections to open the Platforms modal without leaving your draft. Close it after setup to refresh the dashboard’s available destinations. The workspace menu → Settings → Platforms contains the platform controls while Settings → API & MCP contains assistant and developer setup. On mobile, open the navigation menu first. The sidebar’s Updates cards show product news, not delivery status; dismissal is saved only in this browser.

The footer menu shows the Postii logo and your selected personal or company name, without a workspace suffix. Settings lets you edit your first name, last name, and optional company name and choose which appears. Save changes stores these preferences for your signed-in account; this does not create a shared team or change account access. Before customization, the label uses your sign-in name or email, with Personal as the fallback. Settings → Profile → Customize Postii lets you choose a color, mood, and accessory with a live preview. Surprise me makes a random combination; Reset restores the classic look. Changes save automatically and update the bottom-left sidebar; a toast confirms a successful save. This is an account preference, not a shared team setting or an assistant tool. The menu opens upward and offers Usage, Settings, and Log out. Usage opens a nested preview with sample AI usage and a Usage & billing shortcut. Settings opens a modal with Profile, Usage & billing, Platforms, and API & MCP navigation on the left and the selected content on the right. On small screens the navigation moves above the content. Choose Platforms inside it; Platforms in the sidebar opens a full workspace page, not a modal. Settings → Platforms remains a modal. My platforms is the default tab and lists saved connections. All platforms lets you search publishing platforms. Clicking a card opens its platform page; beehiiv connection controls are on that page. Social platforms are marked Coming soon. The marketing homepage modal and Platforms page show only the searchable platform catalog, without My platforms or account controls. The connectors modal filters by All platforms, Social media, or Newsletters; search stays visible above the scrolling results. On a platform page, Connect opens signup for signed-out visitors and resumes onboarding for unfinished accounts. Completed accounts can open connection setup. Assistant and developer setup is in Settings → API & MCP. When a connector or assistant setup dialog opens, the parent modal steps aside. Closing the detail dialog restores the connector list. closing Settings returns to the same view and preserves the draft. Log out asks for confirmation first. Cancel keeps the session open; confirming ends the site session and returns to the homepage.

Usage & billing is a frontend preview with a plan summary, sample usage, and extra-spend controls. Change plan reveals plan, billing-period, and credit-tier selectors. Billing forms and invoices are not shown. Changes last only while the panel is mounted; they do not charge, save billing details, change account access, or enforce usage limits. Payment setup is not connected.

In Dashboard → workspace menu → Settings → Platforms → beehiiv, enter your beehiiv API key, choose Find publications, then select and connect your publication. The server verifies access and encrypts the saved key. A toast confirms success and the publication list updates. A single publication appears by name next to the beehiiv logo. Multiple publications expand from the beehiiv row. The + beside Manage opens Add publication directly. Manage opens the full list: choose Add publication to use a saved key or enter another key. Adding one never replaces another. Open a publication to check its connection, replace its key, or disconnect only that publication with confirmation. Back on the replacement-key screen returns to Manage without changing the saved connection and clears the unsaved key. Successful checks also show a toast. If the initial status cannot load, Connect still opens setup. Failed setup actions show a compact notification at the top; details and the retry link stay in the dialog. Manual activity and delivery checks also confirm their result with a toast. If activity cannot load, a compact message offers Retry without changing connections or resending posts. If both activity sources fail, a single message replaces duplicate errors. Signed-out beehiiv visitors see a Sign in action. Processing is not a published confirmation.

const response = await fetch('/api/v1/connections/beehiiv', {
  credentials: 'same-origin', cache: 'no-store'
});
const result = await response.json();
if (!response.ok) throw new Error(result.error || 'Could not load connection');
console.log(result.data); // Connection metadata only, never your key

Use the connection form for secrets—not the console. Connection writes require the signed-in user and a matching Origin. Each user’s key, publications, and delivery history are isolated from other users. GET returns data.publications; the legacy data.publication alias is present only when exactly one publication is connected. For recheck or discover, send publication_id. Discover lists publications accessible with that publication’s saved key. Connect accepts api_key or source_publication_id with the target publication_id. DELETE uses ?publication_id=YOUR_PUBLICATION_ID and leaves all other connections untouched. Omitting the target is supported only with one connection.

Create, schedule, and publish to beehiiv

Choose specific connected beehiiv publications in Dashboard → Platforms. Add text, submit, then enter a title and choose Save draft, Publish now, or Schedule. Confirm the destination before submitting. Scheduling uses your browser’s timezone and sends an absolute timestamp to beehiiv. The current flow uses plain-text paragraphs, the publication’s default template, and website plus email delivery to free subscribers. Media attachments and combined social/beehiiv sends are not supported yet. Multiple publications share the reviewed content but receive separate requests and results. Partial failures do not resend successful requests. Retry unconfirmed requests keeps each original operation ID.

The API’s create-post endpoint requires beehiiv Max or Enterprise and sufficient key permissions—even for API-created drafts. A connected key does not guarantee Send API access. This is distinct from beehiiv’s OAuth MCP, which supports draft creation on paid plans but is not yet connected to Postii. See our beehiiv setup guide.

// Read-only: inspect delivery activity using your current session.
const response = await fetch('/api/v1/beehiiv/posts', { cache: 'no-store' });
const result = await response.json();
if (!response.ok) throw new Error(result.error);
console.log(result.data);
// For one post, add ?operation_id=YOUR_OPERATION_ID to refresh its status.

POST /api/v1/beehiiv/posts accepts publication_id, title, content, action (draft/publish/schedule), operation_id, confirm: true, and scheduled_at only for scheduling. Obtain explicit user approval first. Reuse the operation ID with identical input on retry. Requests are recorded before sending; duplicates never send again. A 202 response is not proof of publication: inspect data.state. Accepted means beehiiv is processing the post; use Refresh status or Activity → Check status. For uncertain or stuck submitting states, check beehiiv before creating another copy. Scheduled sends run in beehiiv, not a local Postii timer.

Submit and resolve platform barriers

Submit in the composer opens a chat-style readiness review without publishing or saving a post. Edit text and check again, return to edit media or platforms, or skip a destination. Edits apply to the shared draft; separate platform versions and AI rewriting are not built yet. Drafts and attachments remain in browser memory, not durable storage.

The review separates content barriers, missing connections, unavailable Postii features, and checks still needed at delivery. X uses weighted standard-post counting, Bluesky uses graphemes and a byte limit, and TikTok checks different text limits for photo and video posts. Unverified limits are labeled as Postii draft limits, never guaranteed platform approval. Upload processing, video duration, dimensions, account permissions, and live quotas are not fully checked yet.

Connected beehiiv text can continue to its separate confirmation flow; Send API eligibility is still required. Social publishing and media delivery remain unavailable. Homepage Submit opens sign-up directly and keeps text and media locally in this browser for handoff after authentication, for up to 24 hours. This is not a server upload; sign-up does not publish or connect accounts. The API and WebMCP preview endpoints still expose their existing approximate text checks, not this full browser review. Never treat a passing preview as permission or proof that delivery will work.

Endpoints

Dashboard media is local-only: up to 10 images/videos in any mix, 100 MB combined. Text files can be up to 100 KB each and are appended as text, not attachments. These are composer limits, not platform publishing limits; the API does not upload media.

Troubleshooting

The dashboard banner stays below the composer until you close it with × for the current browser session. Connection loading or errors do not hide it; unknown status shows a neutral Manage connections action. Opening setup or changing the connection count does not dismiss it. Its connection button opens the All platforms tab directly so you can browse apps.

Signed-out visitors see Meet Postii: preset FAQ questions with pre-written answers in a chat interface and more suggested questions after each answer. Visitors can also type a question to find an answer from help articles. New chat clears the current conversation and restores starting suggestions. A sign-up shortcut stays available. The conversation stays in page memory; no visitor questions are sent to AI or saved. It does not offer account support or take actions. Signed-in users see Ask Postii!, which suggests local help articles as you type. Pressing Ask Postii explicitly sends your question and recent conversation to the configured AI provider for a knowledge-base-grounded answer. AI is not active until the operator enables Workers AI. It cannot inspect accounts or perform actions. The AI disclaimer appears once a question is submitted. Postii offers troubleshooting or clarification first. When it identifies an issue needing human help, or you ask for a person, its response can offer Submit a support request, opening an editable email and message form for contact@creatorstoolbox.com. This option is not shown after every answer. Submissions are saved privately. Email forwarding requires a configured provider and verified sender; saved does not mean emailed. Only the submitted form, not the full chat, is forwarded. Public article IDs alone are counted when articles are opened; typing does not send search text.

• 401 / sign-in page: reopen the hosted dashboard and sign in. Local development is not a substitute for the hosted beehiiv session.
• 403: use the same-origin connection form; sandbox posts only accept workspace_demo.
• 422: posts return field_errors; beehiiv returns error. Correct the input or API key before retrying.
• 409: the idempotency key was reused with a different payload. Restore the original request or use a new key for a new operation.
• 429 / 502: wait, then retry. For a saved post request, keep the same idempotency key and body.
• 503 on beehiiv: the site’s connection encryption secret needs configuration by the site owner.
• Unexpected redirect: the request was stopped to protect your key. No credentials are forwarded to a redirect target. Contact the site owner if it persists.