---
title: "Share a file"
method: POST
path: "/file/{id}/share"
tags: ["Files"]
---

# Share a file

`POST /file/{id}/share`

## Request

- Base URL: `https://api.elaichi.ai`
- URL: `https://api.elaichi.ai/file/{id}/share`
- Auth: HTTP bearer

Grants one user, one team, or the whole organization the right to open and download the file. `level` must be `view` — a file has nothing to `use` and no settings to `edit`, and an `edit` grantee could re-share data pulled from a connection they may not see — so any other level is `400 invalid_share_level`. Re-granting the same grantee replaces the row rather than stacking one. The grantee must be an active member of this organization (or a team of it), and sharing with yourself is `403`, as on every other resource. A grantee opens the file with the same `GET /file/{id}/content` (and MCP `elaichi://file/{id}`) and sees it in `GET /file` with `access: "view"`; sharing never lets them share, revoke or delete it. Revoking, deleting or letting the file expire takes the access away. Audited as `file.shared`. Owner only: ownership is the gate, and there is no `file:share` permission. A caller who is not the owner gets `403` ("Only the owner…") whenever the file is visible to them in `GET /file` (an explicit share, or `use` on its source connection or toolbox, restricted or not), because they already know it exists; `404` otherwise, including a listed row whose access through a connection or toolbox has broken (`can_open: false` for a lapsed toolbox delegation or a deleted connection).

## Path parameters

- `id` string, required

## Headers

- `X-Organization-Id` string

## Request body

- union
  - ShareRequest: Grants a user, a team, or the whole organization access to the resource at a level. Re-granting the same grantee replaces the level; it never stacks.
    - `grantee_type` 'user' | 'team' | 'org', required: `user` and `team` grants target one `grantee_id`; `org` applies to every member of the organization and takes no id.
    - `grantee_id` string, nullable: User id (`usr_…`) or team id (`team_…`). Omit or send null for `grantee_type: "org"`.
    - `level` 'view' | 'use' | 'edit', required: Same ladder for every shareable resource, low to high. `view` — see it exists, read its metadata/config; cannot exercise it. `use` — `view` + exercise it, resource-specific: run tools through a connection; execute a toolbox's tools through its bound connections (this DELEGATES — the caller runs through each entry's pinning editor's own authority, not necessarily their own); stamp a new toolbox by copying a template's entries; create connections from a connector. `edit` — `use` + change its settings, entries and its own grants.
  - ShareManyRequest: Share with several grantees at one level. Partial success: each grantee is granted or refused on its own, and only a request where nobody is granted answers 400 `share_grantees_rejected` (every reason in `error.details.rejected`). Duplicates collapse to one grant.
    - `grantees` object[], required
      - `grantee_type` 'user' | 'team' | 'org', required: `user` and `team` grants target one `grantee_id`; `org` applies to every member of the organization and takes no id.
      - `grantee_id` string, nullable: User id (`usr_…`) or team id (`team_…`). Omit or send null for `grantee_type: "org"`.
    - `level` 'view' | 'use' | 'edit', required: Same ladder for every shareable resource, low to high. `view` — see it exists, read its metadata/config; cannot exercise it. `use` — `view` + exercise it, resource-specific: run tools through a connection; execute a toolbox's tools through its bound connections (this DELEGATES — the caller runs through each entry's pinning editor's own authority, not necessarily their own); stamp a new toolbox by copying a template's entries; create connections from a connector. `edit` — `use` + change its settings, entries and its own grants.

## Response `201`

Created

- union
  - AclEntry: One access grant on a connection, toolbox, template, connector or (at `view` only) a stored tool file.
    - `id` string: Grant id (`acl_…`), the `{aclId}` that `DELETE .../share/{aclId}` takes.
    - `resource_type` 'connection' | 'toolbox' | 'template' | 'connector' | 'file'
    - `resource_id` string: The shared resource's id (a connector's slug, for that type).
    - `grantee_type` 'user' | 'team' | 'org': `user` and `team` grants target one `grantee_id`; `org` applies to every member of the organization and takes no id.
    - `grantee_id` string, nullable: User id (`usr_…`) or team id (`team_…`). Null for a `grantee_type: "org"` grant.
    - `level` 'view' | 'use' | 'edit': Same ladder for every shareable resource, low to high. `view` — see it exists, read its metadata/config; cannot exercise it. `use` — `view` + exercise it, resource-specific: run tools through a connection; execute a toolbox's tools through its bound connections (this DELEGATES — the caller runs through each entry's pinning editor's own authority, not necessarily their own); stamp a new toolbox by copying a template's entries; create connections from a connector. `edit` — `use` + change its settings, entries and its own grants.
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - ShareManyResponse: The answer to a `grantees` share: the grants as written, and everyone who was not granted with the code the single form would have answered (`share_target_is_self`, `share_target_is_owner`, `member_not_active`, `bad_request`). A resource's own extra fields (a toolbox's `delegation`) ride alongside.
    - `result` AclEntry[]
      - `id` string: Grant id (`acl_…`), the `{aclId}` that `DELETE .../share/{aclId}` takes.
      - `resource_type` 'connection' | 'toolbox' | 'template' | 'connector' | 'file'
      - `resource_id` string: The shared resource's id (a connector's slug, for that type).
      - `grantee_type` 'user' | 'team' | 'org': `user` and `team` grants target one `grantee_id`; `org` applies to every member of the organization and takes no id.
      - `grantee_id` string, nullable: User id (`usr_…`) or team id (`team_…`). Null for a `grantee_type: "org"` grant.
      - `level` 'view' | 'use' | 'edit': Same ladder for every shareable resource, low to high. `view` — see it exists, read its metadata/config; cannot exercise it. `use` — `view` + exercise it, resource-specific: run tools through a connection; execute a toolbox's tools through its bound connections (this DELEGATES — the caller runs through each entry's pinning editor's own authority, not necessarily their own); stamp a new toolbox by copying a template's entries; create connections from a connector. `edit` — `use` + change its settings, entries and its own grants.
      - `created_at` string, date-time
      - `updated_at` string, date-time
    - `rejected` object[]
      - `grantee_type` 'user' | 'team' | 'org': `user` and `team` grants target one `grantee_id`; `org` applies to every member of the organization and takes no id.
      - `grantee_id` string, nullable
      - `code` string
      - `message` string

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `429`: Rate limited

---

[API](https://skmtc.dev/elaichi/apis/elaichi-api.md) · [All operations](https://skmtc.dev/elaichi/apis/elaichi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/elaichi/apis/elaichi-api/revisions/b22cfb7b6d15?raw)