---
title: "Link workspace field group"
method: POST
path: "/v1/projects/{project_id}/workspace-field-groups"
tags: ["Projects"]
---

# Link workspace field group

`POST /v1/projects/{project_id}/workspace-field-groups`

## Request

- Base URL: `https://dovetail.com/api`
- URL: `https://dovetail.com/api/v1/projects/{project_id}/workspace-field-groups`
- Auth: HTTP bearer

Link a workspace field group to a project so the group's fields are available on that project's data and docs. For callers with write permission, linking the same group twice is a no-op.

Returns `200` when the preflight lookup finds an existing link. Otherwise, returns `201` after the create attempt succeeds; concurrent first-time requests may therefore both return `201`.

> 🚧 Permissions
>
> Please check you have the relevant permissions required to access this resource. This may include specific permissions on the object itself or its parent, or having the correct user role if you're making updates.

**Required scope:** `project:write`

## Path parameters

- `project_id` string, required

## Request body

- object
  - `workspace_field_group_id` string, required: Unique identifier of the workspace field group to link. This is the same ID used by field endpoints as `workspace_field_group_id` (the path segment in `/settings/fields/{id}`).

## Response `200`

200

- object
  - `data` object, required
    - `id` string, required
    - `url` string: The URL of this resource in the Dovetail web app. This field is experimental and may change without notice.
    - `title` string, required
    - `type` 'workspace_field_group', required
    - `created_at` string, required

## Other responses

- `201`: 201
- `400`: 400
- `401`: 401
- `403`: 403
- `404`: 404
- `422`: 422
- `429`: 429
- `500`: 500

## Changes

- **2026-11-03** `8abea327e6b9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/dovetail/apis/dovetail-public-api/changes/v1/projects/:project_id/workspace-field-groups/post.md)

---

[API](https://skmtc.dev/dovetail/apis/dovetail-public-api.md) - [All operations](https://skmtc.dev/dovetail/apis/dovetail-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/dovetail/apis/dovetail-public-api/revisions/8abea327e6b9?raw)