Drive

Share a file

POST/api/v1/drive/files/:id/share

Who can use this: Any signed-in accountAs Markdown

Every share is a link. Leave out shared_with for a public link that anyone who has it can open, to pass on yourself. Name a person and the link opens only for them, signed in as that address (and for you); it also shows in their list of shares, and they are emailed the link. notice says plainly what happened, including when no email went out.

Parameters

Name	Where	What it is
id required	path	The file's id.e.g. 42
shared_with	query	The address of the person to share with. Leave it out for a public link.e.g. friend@example.com
expires_days	query	The link stops working after this many days (1 to 9999). Leave it out for a link that lasts until you revoke it.

Good to know

Sharing with an address that has no account still makes the share, but sends no email (emailed is false), and the link opens only once someone signs in as that address. For anyone without an account, make a public link.
You can't share with yourself (400). A file that isn't yours, or is in Trash, answers 404.
While the file is in Trash its link stops working, and deleting it for good ends the share.

curl -s -X POST 'https://api.mailmasker.org/api/v1/drive/files/42/share?shared_with=friend%40example.com' \
  -H "Authorization: Bearer $TOKEN"

use Mojo::Base -strict;
use Mojo::UserAgent;

my $ua  = Mojo::UserAgent->new;
my $res = $ua->post('https://api.mailmasker.org/api/v1/drive/files/42/share',
    { Authorization => "Bearer $ENV{TOKEN}" },
    form => { shared_with => 'friend@example.com' })->result;
die $res->code, ' ', ($res->json('/error') // $res->message), "\n" unless $res->is_success;
print $res->body, "\n";

There's no homelab-cli command for this yet.

Response 201 Created

{
  "ok": true,
  "id": 15,
  "token": "5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e",
  "url": "https://drive.example.com/s/5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e5ca1ab1e",
  "target": "file",
  "label": "notes.txt",
  "shared_with": "friend@example.com",
  "public": false,
  "emailed": true,
  "notice": "Shared with friend@example.com and emailed them the link."
}