Workspaces
Workspaces, labels, and how isolation works across them.
A workspace holds accounts, posts, media, and team members. Agencies use one per client, brands use one per brand. Nothing crosses between them.
Isolation
Every request is scoped to a workspace the caller belongs to. Naming a workspace you have no access to answers 404, and list endpoints return only what you can see. There is no privileged read path: the same check applies to the dashboard, an API key, and the agent.
An API key bound to a workspace is confined to it even if the account owns others. That is the safest shape for an integration serving one client.
Endpoints
Workspace endpoints need the workspaces scope.
| Endpoint | What it does |
|---|---|
GET /v1/workspaces | Workspaces the caller can reach |
POST /v1/workspaces | Create one |
GET /v1/workspaces/{id} | One workspace |
PUT /v1/workspaces/{id} | Rename or update it |
DELETE /v1/workspaces/{id} | Delete it, and everything in it |
GET /v1/workspaces/{id}/analytics | Roll-up for the workspace |
Workspaces are unlimited and free: you pay per connected account, not per workspace. See Pricing.
Labels
Labels organise posts inside a workspace: by campaign, by client, by content pillar. They are also the unit the label analytics roll-up aggregates on, so labelling at publish time is what makes campaign reporting possible later.
Label endpoints need the labels scope.
| Endpoint | What it does |
|---|---|
GET /v1/labels | List labels |
POST /v1/labels | Create one |
GET /v1/labels/{id} | One label |
PUT /v1/labels/{id} | Update it |
DELETE /v1/labels/{id} | Delete it. Posts keep existing |
Attach labels with the labels array when creating a post, or apply them to many posts at once with the label action on POST /v1/posts/bulk.
Activity
GET /v1/activity lists what happened in your workspaces, newest first. It needs the analytics scope. Events are kept for 90 days, except security events, which are append-only and kept indefinitely.
| Kind | Recorded when |
|---|---|
publish | A post finishes publishing: published, failed, or partially failed |
connection | An account is connected, disconnected, or changes health |
webhook | A webhook delivery succeeds, or fails with no retries left |
inbox | A reply is sent from the inbox |
automation | An automation run completes or fails |
billing | A usage invoice is issued, covered by credit, or fails to charge |
security | The audit log: members joining, leaving, or changing role or access, and changes to two-step verification, passkeys, single sign-on, and signed-in devices |
| Parameter | What it does |
|---|---|
workspace_id | One workspace. Omit it to read every workspace you belong to |
kind | One of the kinds above |
from, to | ISO 8601 time window |
cursor | meta.next_cursor from the previous page |
limit | 1 to 100, default 50 |
Filtering to kind=security gives you the audit log: who changed access or a security setting, and when. Those rows are never rewritten and never expire.
Each event carries a summary and an actor: the type (user, api_key, agent, or system) and a name where there is one. GET /v1/logs is separate: it lists raw API requests, not workspace events.
Request logs
GET /v1/logs lists the raw API requests of the last 30 days, newest first, with the same workspace_id, days, limit, and cursor parameters. Each row carries the method, route, path, status_code, duration_ms, platform, and the error message of a failed call, plus who made it:
| Field | |
|---|---|
source | dashboard, mcp, sdk-<language>, cli, github-action, integration, api, or oauth |
api_key_name | The key's name when the call used one |
Filter with status (success or failed), method, platform, route, q (path and message text), or source, where sdk matches every SDK.
Next
Related documentation
- API Overview
Base URL, envelopes, pagination, and errors for the FoPost REST API.
- 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.
- Blog
A keyword plan, articles written in the background, a review window, and a target they publish to.
- Blogs and Articles
Read and manage the articles and products that already live on a connected site.