REST APIGET

Workspaces

List the workspaces an API key or OAuth sign-in can act in, with the role and abilities in each, and pick one per request with the X-Workspace-Id header.

GEThttps://post.adaptlypost.com/post/api/v1/workspaces

Lists the workspaces the calling key or OAuth sign-in can act in, with your role and what you can do in each. Any valid key can call it, whatever its role.

API Key (Bearer token)
Permission:any valid keyRoles and permissions

When to call it

Call it when an integration starts, before it reads or writes anything. An OAuth connection, such as the Claude or ChatGPT connector, reaches every workspace its member belongs to, across organizations. An API key reaches only its own workspace, so the list has one entry.

If you are an agent: when the list has more than one workspace and the user has not named one, ask which to use. Then send its id in X-Workspace-Id on every call, and read its can before you offer to schedule or publish.

Response fields

FieldDescription
idThe workspace ID. Send it in the X-Workspace-Id header to act in this workspace.
nameThe workspace name.
organizationThe organization that owns the workspace, with its id and name.
roleYour role in this workspace: key is one of admin, editor, contributor, viewer; name is the label in your language. For an API key, the key's role.
isDefaultTrue for the workspace a call lands in when it sends no X-Workspace-Id header.
currentTrue for the workspace this call landed in.
canThree booleans, draft, schedule and publish, for what your role allows with posts in this workspace.

Choose a workspace with X-Workspace-Id

Every endpoint accepts an optional X-Workspace-Id header. Set it to an id from this list and the call runs in that workspace, with your role there. Without it the call lands in the default workspace.

Request header
X-Workspace-Id: ag_02k7m

A workspace the caller cannot reach answers 403 with code workspace_access_denied and the workspaceId it refused. An API key belongs to one workspace, so it gets the same 403 for any other workspace's id: send the key's own workspace id or leave the header out.

403 Forbidden: workspace access denied
{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "workspace_access_denied",
  "workspaceId": "ag_03p4r",
  "message": "You have no access to workspace ag_03p4r. Call GET /workspaces to list the workspaces you can use, and send one of those ids in the X-Workspace-Id header."
}
List your workspaces
curl --request GET \
  --url https://post.adaptlypost.com/post/api/v1/workspaces \
  --header 'Authorization: Bearer <api-key>'
Act in another workspace
curl --request GET \
  --url https://post.adaptlypost.com/post/api/v1/social-accounts \
  --header 'Authorization: Bearer <oauth-token>' \
  --header 'X-Workspace-Id: ag_02k7m'
200
{
  "workspaces": [
    {
      "id": "ag_01j9x",
      "name": "Acme",
      "organization": { "id": "org_01hzq", "name": "Acme Agency" },
      "role": { "key": "editor", "name": "Editor" },
      "isDefault": true,
      "current": true,
      "can": { "draft": true, "schedule": true, "publish": true }
    },
    {
      "id": "ag_02k7m",
      "name": "Client B",
      "organization": { "id": "org_02abc", "name": "Client B Inc" },
      "role": { "key": "contributor", "name": "Contributor" },
      "isDefault": false,
      "current": false,
      "can": { "draft": true, "schedule": false, "publish": false }
    }
  ]
}