Share an artifact

PUT/workspaces/{workspace}/artifacts/{artifact_id}/access

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 as Authorization: Bearer.
• MCP tool: artifact with action share, and the same inputs
• Scope: An access token needs artifacts:admin.

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

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:

{
  "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.

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.