API Overview

Base URL, envelopes, pagination, and errors for the FoPost REST API.

The FoPost REST API is what the dashboard itself runs on. Anything you can do in the app you can do from your own code: create posts, schedule them, attach media, read analytics, drive automations, and receive webhooks.

Base URL

https://api.fopost.com/v1

Every path in this reference is relative to that base. The machine-readable spec is served at /v1/openapi.json and is the source this reference is written from.

Authentication

Send your API key in the X-API-Key header:

curl https://api.fopost.com/v1/posts \
  -H "X-API-Key: $FOPOST_API_KEY"

Keys carry scopes, and a key may be bound to a single workspace. See Authentication.

Response envelope

A single resource is returned bare:

{
  "id": "0f1c4a1e-8f3c-4c62-9f6a-2a4b1a9e77d1",
  "workspace_id": "7d2b8c11-4e5a-4a8f-b0d9-3c5e6f7a8b90",
  "status": "scheduled"
}

A collection is wrapped in data with a meta block:

{
  "data": [ { "id": "0f1c4a1e-...", "status": "published" } ],
  "meta": { "page": 1, "per_page": 30, "total": 214, "total_pages": 8 }
}

A call that has nothing to return, such as a delete, answers 204 No Content with an empty body.

Every key in a response, and every query parameter, is snake_case. Request bodies take the field names each endpoint documents. The ads endpoints are the one exception: their responses keep camelCase keys.

Request ids

Every response carries an X-Request-Id header. Quote it when you contact support about a call.

Pagination

List endpoints take page (default 1) and per_page (default 30, maximum 100). Read meta.total_pages rather than paging until you get an empty array.

curl "https://api.fopost.com/v1/posts?page=2&per_page=50" \
  -H "X-API-Key: $FOPOST_API_KEY"

Feeds that grow while you read them page by cursor instead. Their meta is { "next_cursor": "…", "has_more": true }; pass next_cursor back as the parameter the endpoint names, and stop when has_more is false. The ads endpoints keep their own nextCursor and after.

Identifiers and timestamps

Resource ids are UUIDs. Timestamps are ISO 8601 in UTC (2026-08-29T14:30:00.000Z), and any time you send is interpreted the same way, so convert local times before sending them.

Errors

Errors use one envelope on every endpoint:

{
  "error": "validation_error",
  "message": "accounts must contain at least one account id"
}

error is the stable machine-readable code, message is for humans and may change. Some errors add context fields, such as retry_after on a 429. An unknown route and a fault on our side answer with the same envelope (not_found and internal_error), never with plain text.

StatusMeaning
200Success
201Created
400Malformed request, a failed validation (validation_error) or a bad identifier
401Missing or invalid API key
402Usage credit exhausted with no payment method on file
403Key lacks the required scope
404No such resource, or a resource in a workspace you do not belong to
409The request conflicts with the current state of the resource
413The body is larger than the endpoint accepts
422A platform refused the request; message carries its reason
429Rate limited. See Rate Limits for the per-plan ceiling and the retry_after field
500Something broke on our side
502A platform or provider answered with something we could not use
503The feature is not configured for this deployment, or its provider is down

A resource in a workspace you do not belong to answers the same 404 as one that does not exist, so the API never lets you probe for other tenants' data.

Versioning

The version lives in the path. /v1 will not change shape under you: new fields and new endpoints are added, existing fields are not removed or repurposed. Treat unknown fields in a response as forward compatible and ignore them.

Where to go next

Related documentation
  • Authentication

    API keys, scopes, and workspace binding.

  • Publishing

    Create a post, target accounts, publish it, and read the per-account result.

  • Scheduling

    Schedule a post, repeat it, and import a batch from a spreadsheet.

  • Media

    Upload files, list the media library, and attach media to a post.

  • Validation

    Check content, text length, and media against platform rules before a post exists.

  • Accounts

    List connected social accounts, check their health, and refresh credentials.

  • Workspaces

    Workspaces, labels, and how isolation works across them.

  • Analytics

    Overview totals, time series, top posts, decay, cadence, demographics, and label roll-ups.

Was this helpful?

On this page