Workspaces

Workspaces group an organization’s forms, Private Templates, and assets. Every form belongs to one workspace, named by workspace_public_id on the form resource. The Platform API manages workspaces with the same rules as the sidebar in the app, described in Workspaces, and every write reaches open editors at once.

Operation	What it does	Permission
GET /v1/workspaces	Lists the active workspaces in sidebar order.	forms:read or templates:read
GET /v1/workspaces/{workspace_public_id}	Reads one workspace.	forms:read or templates:read
POST /v1/workspaces	Creates a workspace.	workspace_management
PATCH /v1/workspaces/{workspace_public_id}	Renames, restyles, or reorders a workspace.	workspace_management

Every call costs one credit. workspace_management is the role permission that lets a member create and edit workspaces in the app; Admins and Members have it by default. A missing permission is 403 FORBIDDEN with the permission named in required_permission.

Listing and reading workspaces

curl -s -H "Authorization: Bearer $FOMR_TOKEN" \
  https://platform.fomr.io/v1/workspaces

The list holds every active workspace: the Default Workspace first, then the others in the order the sidebar shows them. The response is { data } with no cursor.

GET /v1/workspaces

{
  "data": [
    {
      "public_id": "Mn1w",
      "name": "Main",
      "is_default": true,
      "color": "zinc",
      "icon": "home"
    },
    {
      "public_id": "Wk02",
      "name": "Events",
      "is_default": false,
      "color": "red",
      "icon": "calendar"
    },
    {
      "public_id": "Wk03",
      "name": "Hiring",
      "is_default": false,
      "color": "orange",
      "icon": null
    }
  ]
}

Every field of a workspace is listed in the response of Read a workspace.

GET /v1/workspaces/{workspace_public_id} answers one workspace in the same shape. A deleted workspace, or a workspace of another organization, answers 404 NOT_FOUND.

Use a workspace ID to filter the form list, to create or generate a form in that workspace, or to move a form.

Creating a workspace

curl -s -X POST https://platform.fomr.io/v1/workspaces \
  -H "Authorization: Bearer $FOMR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Customer research"}'

POST /v1/workspaces answers 201 with the new workspace, placed last in the sidebar.

201 Created

{
  "public_id": "Wk04",
  "name": "Customer research",
  "is_default": false,
  "color": "amber",
  "icon": null
}

Every field of the request body is listed under Create a workspace.

• The name is trimmed and must be unique. Two active workspaces cannot share a name, compared without regard to case, so Marketing and marketing collide. A taken name is 400 INVALID_INPUT with an issue of code workspace_name_taken at path ["name"].
• Color and icon default as in the app. Left out, color is the first color no other workspace uses, or indigo once all ten are taken, and icon is null, which shows the initial letter.
• Creating needs Pro. A Free organization gets 402 PRO_FEATURE_REQUIRED with feature: "workspaces". An organization at its plan’s max_workspaces limit gets 402 PLAN_LIMIT_REACHED with limit.key: "max_workspaces". Errors describes both bodies.
• A failed create writes nothing and spends no credits, as on createForm.

400 INVALID_INPUT

{
  "code": "INVALID_INPUT",
  "message": "The request is not valid.",
  "request_id": "0f3c2a9e-6b1d-4e57-9a1c-2d8e4f6b7c90",
  "issues": [
    {
      "code": "workspace_name_taken",
      "message": "Another active workspace already has this name",
      "path": [
        "name"
      ]
    }
  ]
}

Updating a workspace

PATCH /v1/workspaces/{workspace_public_id} changes the fields you send and answers the workspace. Fields you leave out keep their value, and a call that changes nothing writes nothing.

curl -s -X PATCH https://platform.fomr.io/v1/workspaces/Wk03 \
  -H "Authorization: Bearer $FOMR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Recruiting","icon":"users","position":0}'

Every field of the request body is listed under Update a workspace.

• Renaming follows the create rules. The new name must be unique among the other active workspaces; changing only its case is allowed.
• position reorders like a drag in the sidebar. It counts from 0 among the workspaces after the Default Workspace. A position past the end places the workspace last, and the others shift to make room.
• The Default Workspace can be renamed and restyled, but not moved. Sending position for it is 400 INVALID_INPUT at path ["position"].
• Editing needs no plan feature. An organization that moved back to Free can still rename, restyle, and reorder the workspaces it has.

Deleting a workspace

The Platform API does not delete workspaces. Deleting one unpublishes every form in it and moves all of its items to Trash at once, and the workspace itself cannot be restored, so it stays an action a member takes in the app. To retire a single form, move it to Trash instead.

Errors

Status	Code	When
400	INVALID_INPUT	The body has an unknown field or a value outside the allowed colors, icons, or name length; the name is taken; or position targets the Default Workspace.
402	PRO_FEATURE_REQUIRED	A Free organization creates a workspace.
402	PLAN_LIMIT_REACHED	The organization is at its max_workspaces limit.
403	FORBIDDEN	The token’s member lacks workspace_management.
404	NOT_FOUND	The workspace does not exist, was deleted, or belongs to another organization.

Errors describes the envelope every error shares.