# Share an artifact

> Change who can open an artifact.

<div class="g1t-endpoint"><span class="g1t-method" data-method="put">PUT</span><code>/workspaces/{workspace}/artifacts/{artifact_id}/access</code></div>

Share it with a person (username), a team (team: its slug) or an agent (agent: its id), or a principal from its access list, at role view, comment, edit or manage (full access), with an optional notify message; role none takes theirs away. Set general_access to none (only people invited), workspace (everyone in the workspace) or link (anyone in the workspace with the link), with general_role view, comment or edit. inherit false stops it following its space or parent; true follows again. agent_mode suggest or edit says how agents change it (null follows its space). Takes full access (manage). Returns who can open it now.

One call can share with one person, team or agent, and change `general_access`, `inherit` and `agent_mode`, in that order. `role` set to `none` takes someone's access away. General access never gives full access. On an artifact that follows the doc it is under, change general access on that doc, or set `inherit` to false first.

- **Authentication:** Required. Send an [access token](/reference/api/#authentication) as `Authorization: Bearer`.
- **MCP tool:** [`artifact`](/reference/mcp/#artifact) with `action` `share`, and the same inputs
- **Scope:** An access token needs [`artifacts:admin`](/guides/authentication/#scopes).

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace` | string | Yes | The workspace's slug, e.g. "acme". |
| `artifact_id` | string | Yes | The artifact's id (fol_…), or its address: /acme/-/artifacts/q4-roadmap-fol_… |

## Body parameters

Send a JSON object. Names are `snake_case`, as in responses; the `camelCase` spelling is accepted too.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `username` | string | No | A member to share it with. |
| `team` | string | No | A team of the workspace to share it with: its slug. |
| `agent` | string | No | An agent of the workspace to share it with: its id. |
| `principal` | string | No | Who, as its access list names them: user:…, agent:… or team:… |
| `role` | string | No | What they may do: view, comment, edit, or manage (full access, sharing included); none takes their access away. One of `view`, `comment`, `edit`, `manage`, `none`. |
| `notify` | string | No | A message for the person it is shared with. |
| `general_access` | string | No | none (only people invited), workspace (everyone in the workspace) or link (anyone in the workspace with the link). One of `none`, `workspace`, `link`. |
| `general_role` | string | No | What general access gives; never full access. One of `view`, `comment`, `edit`. |
| `inherit` | boolean | No | Whether it follows its space or the doc it is under. |
| `agent_mode` | string or null | No | How agents change it: suggest or edit; null follows its space. One of `suggest`, `edit`, `null`. |

## Example request

```sh
curl -X PUT https://api.g1t.sh/workspaces/acme/artifacts/fol_01kq7c4e6g8j0m2p4r6t8v0x2z/access \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "bo",
    "role": "edit",
    "notify": "Can you fill in the dates?"
  }'
```

## Example response

A successful request answers `200` with:

```json
{
  "artifact_id": "fol_01kq7c4e6g8j0m2p4r6t8v0x2z",
  "owner": {
    "type": "user",
    "id": "usr_01kkntcg1eeb98j62xjm7eh09q",
    "username": "ana",
    "display_name": "Ana Lima"
  },
  "shared_with": [
    {
      "principal": "user:usr_01kmb2d4f6h8k0m2p4r6t8v0x2",
      "member": {
        "type": "user",
        "id": "usr_01kmb2d4f6h8k0m2p4r6t8v0x2",
        "username": "bo",
        "display_name": "Bo Chen"
      },
      "role": "edit",
      "inherited_from": null
    },
    {
      "principal": "team:design",
      "member": {
        "type": "team",
        "slug": "design",
        "display_name": "@acme/design"
      },
      "role": "comment",
      "inherited_from": null
    }
  ],
  "general_access": "workspace",
  "general_role": "view",
  "inherit": true,
  "inherited_from": {
    "type": "space",
    "id": "spc_01kq1a3c5e7g9j1l3n5q7s9u1w",
    "name": "General"
  },
  "agent_mode": null,
  "can_share": true
}
```

## Errors

A failed request answers with one of these statuses and a body like `{"error": {"code": "not_found", "message": "Repository not found."}}`. See [errors](/reference/api/#errors).

| Status | Code | When |
| --- | --- | --- |
| 401 | `unauthenticated` | A token is required, or the one sent is not valid. |
| 403 | `forbidden` | The token is valid but not allowed to do this, such as a member-only change or an agent token outside its repository. |
| 404 | `not_found` | It does not exist, or you cannot see it. |
| 409 | `conflict` | The request conflicts with the current state. |
| 422 | `invalid` | The input is not valid. `message` says which field and why. |