Skip to content
FLORA FLORA API

Share a project by link

POST
/projects/{projectId}/share
 
import { FloraClient } from '@flora-ai/flora';


const client = new FloraClient({ apiKey: process.env['FLORA_API_KEY'] });


const sharing = await client.projects.sharing.share({
  projectId: '<projectId>',
  access: 'view',
});
console.log(sharing);

Shares the project the way the canvas Share tab does and returns the link: opens link sharing at the requested access (view or edit) and returns the reusable link for that access, creating it on first use. Escalate-only — sharing for view never downgrades a project already shared for edit; use PATCH /projects/{project_id}/sharing to lower or restrict access. edit requires the workspace plan to include editable sharing and returns paid_plan_required otherwise; a caller who may not manage the project’s sharing gets forbidden. Anyone holding the returned link gets its role. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.

Error responses use the standard error body.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
projectId
required

Project identifier

string
/^prj_\S+$/

Project identifier

Request Body required

Section titled “Request Body required ”
Media type application/json
object
access
required

What the link should grant. edit needs the workspace plan to include editable sharing (otherwise paid_plan_required). Never downgrades: a project already shared for editing stays that way and its view link is returned.

string
Allowed values: view edit
allow_comments

Whether visitors arriving through the link may leave comments. Omit to keep the current setting (on by default).

boolean
passphrase

Require this passphrase before the link resolves. Stored hashed; omit to keep the current setting. Whitespace-only values are rejected.

string
>= 1 characters <= 200 characters

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Project shared; link returned.

Media type application/json
object
project_id
required

Project identifier

string
/^prj_\S+$/
workspace_id
required

Workspace identifier

string
/^ws_\S+$/
url
required

Link into the project. Anyone who has it gets the link’s role, so treat it as a secret.

string format: uri
role
required

What the link grants: guest can view (and comment when allowed), editor can edit

string
Allowed values: guest editor
sharing_mode
required

Link sharing mode: restricted (no links; members only), view (anyone with the link can view), edit (anyone with the link can edit)

string
Allowed values: restricted view edit
created
required

True when this call created the link; false when an existing link was returned

boolean
canvas_url
required

Project canvas URL

string format: uri
Example 
{
  "project_id": "prj_abc123",
  "workspace_id": "ws_abc123",
  "role": "guest",
  "sharing_mode": "restricted"
}