API reference

Sharing

Share a resource with people, groups, circles or a link, change and pause what each sees, accept offers, and see what is shared with you.

A resource is named <app>:<type>:<id> (a car is vehicles:vehicle:veh_…), URL-encoded in paths. You share only what you hold, and never more than you hold. Someone outside your circles or organization accepts a share before it gives them anything. Reading needs sharing:read; sharing, changing, pausing and ending need sharing:write. A person's live location is shared through Find My instead.

What you hold on a resource and where it comes from (you). If you may share it, also who has access (each grant with its rev, preset, limits and whether the owner organization's policy blocks it), its links, invitations to addresses with no account, and the owner organization's policy. No access, or no such resource, is 404.

Auth: user access token or platform agent key

Path parameter	Description
`:rn`	A resource's name, `<app>:<type>:<id>` (`vehicles:vehicle:veh_…`), URL-encoded (`vehicles%3Avehicle%3Aveh_…`). The owner's space is read from the stored resource, never from the name.

Response 200

{
  resource: string
  type: string
  app: string
  label: string
  owner: {
    spaceId: string
    kind: "org" | "personal"
    name: null | string
    you: boolean
  }
  you: {
    capabilities: string[]
    via: {
      kind: "role" | "owner" | "container"
      detail?: string
      capabilities: string[]
    } | {
      kind: "link" | "grant"
      resource: string
      inherited: boolean
      principal: string
      source: string
      preset?: string
      capabilities: string[]
      params?: {
        [key: string]: boolean | string | number
      }
      notBefore?: number
      expiresAt?: number
      schedule?: {
        tz: string
        windows: {
          days: object
          from: string
          to: string
        }[]
      }
      approval?: string[]
      assistants?: boolean
      paused?: true
    }[]
    canShare: boolean
  }
  grants: null | {
    resource: string
    principal: string
    kind: "user" | "key" | "org" | "link" | "group" | "circle"
    name: null | string
    email: null | string
    deleted: boolean
    source: string
    status: "active" | "pending"
    capabilities: string[]
    preset: null | string
    notBefore: null | number
    expiresAt: null | number
    schedule: null | {
      tz: string
      windows: {
        days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
      }[]
    }
    params: null | {
      [key: string]: boolean | string | number
    }
    assistants: boolean
    approval: string[]
    includeGuests: boolean
    external: boolean
    blocked: null | string
    acceptBy: null | number
    pausedUntil: null | number
    grantedBy: {
      id: string
      name: null | string
    }
    createdAt: string
    updatedAt: string
    rev: number
  }[]
  links: null | {
    linkId: string
    resource: string
    audience: "org" | "anyone" | "signed_in"
    capabilities: string[]
    preset: null | string
    expiresAt: null | number
    passwordProtected: boolean
    blocked: null | string
    createdBy: {
      id: string
      name: null | string
    }
    createdAt: string
  }[]
  invitations: null | {
    invitationId: string
    principal: string
    email: string
    capabilities: string[]
    preset: null | string
    notBefore: null | number
    expiresAt: null | number
    schedule: null | {
      tz: string
      windows: {
        days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
      }[]
    }
    params: null | {
      [key: string]: boolean | string | number
    }
    assistants: boolean
    approval: string[]
    offerEnds: number
    invitedBy: {
      id: string
      name: null | string
    }
    createdAt: string
  }[]
  policy: null | {
    externalSharing: "off" | "accounts" | "links"
    allowedDomains: string[]
    linkMaxDays: null | number
  }
}

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:read

Shares a resource with a person (by user id or email address), group, circle, organization or key: a preset or a list of capabilities, and optionally notBefore, expiresAt, a weekly schedule, params, assistants, approval and a message. You can give no more than you hold. 201 with { kind: "grant" } (pending when the person must accept) or, for an address with no account, { kind: "invitation" }, which becomes a pending grant when they sign up. 403 external_sharing_off when the owner organization's policy refuses it, 403 capability_not_held_to_grant for more than you hold, 429 past the daily limit.

Auth: user access token or platform agent key

Path parameter	Description
`:rn`	A resource's name, `<app>:<type>:<id>` (`vehicles:vehicle:veh_…`), URL-encoded (`vehicles%3Avehicle%3Aveh_…`). The owner's space is read from the stored resource, never from the name.

Request body

Field	Type	Required	Notes
`principal`	`object \| object`	Yes
`preset`	`string`	No	up to 32 characters
`capabilities`	`string[]`	No	1–32 items; each up to 32 characters
`notBefore`	`integer`	No	> 0
`expiresAt`	`integer`	No	> 0
`schedule`	`object`	No
`schedule.tz`	`string`	Yes	1–64 characters
`schedule.windows`	`object[]`	Yes	1–8 items
`schedule.windows[].days`	`("sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat")[]`	Yes	1–7 items
`schedule.windows[].from`	`string`	Yes	up to 5 characters
`schedule.windows[].to`	`string`	Yes	up to 5 characters
`params`	`object`	No	keys up to 32 characters; values: string (up to 64 characters), number or boolean
`assistants`	`boolean`	No
`approval`	`string[]`	No	up to 32 items; each up to 32 characters
`includeGuests`	`boolean`	No
`message`	`string`	No	up to 500 characters
`notify`	`boolean`	No

Also checked: Unknown fields are rejected.

Response 201

{
  kind: "grant"
  grant: {
    resource: string
    principal: string
    kind: "user" | "key" | "org" | "link" | "group" | "circle"
    name: null | string
    email: null | string
    deleted: boolean
    source: string
    status: "active" | "pending"
    capabilities: string[]
    preset: null | string
    notBefore: null | number
    expiresAt: null | number
    schedule: null | {
      tz: string
      windows: {
        days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
      }[]
    }
    params: null | {
      [key: string]: boolean | string | number
    }
    assistants: boolean
    approval: string[]
    includeGuests: boolean
    external: boolean
    blocked: null | string
    acceptBy: null | number
    pausedUntil: null | number
    grantedBy: {
      id: string
      name: null | string
    }
    createdAt: string
    updatedAt: string
    rev: number
  }
} | {
  kind: "invitation"
  invitation: {
    invitationId: string
    principal: string
    email: string
    capabilities: string[]
    preset: null | string
    notBefore: null | number
    expiresAt: null | number
    schedule: null | {
      tz: string
      windows: {
        days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
      }[]
    }
    params: null | {
      [key: string]: boolean | string | number
    }
    assistants: boolean
    approval: string[]
    offerEnds: number
    invitedBy: {
      id: string
      name: null | string
    }
    createdAt: string
  }
}

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:write

Changes a grant made directly: send the rev you read and the fields to change (null clears notBefore, expiresAt, schedule, params and approval; naming preset replaces the capabilities and settings). The result is held to the same rules as a new grant. 409 stale (with the grant as it is now) when someone changed it first. ?source= picks one when a principal holds several.

Auth: user access token or platform agent key

Path parameter	Description
`:rn`	A resource's name, `<app>:<type>:<id>` (`vehicles:vehicle:veh_…`), URL-encoded (`vehicles%3Avehicle%3Aveh_…`). The owner's space is read from the stored resource, never from the name.
`:principal`	Who a grant is to, URL-encoded: `user:usr_…`, `group:team_…`, `circle:cir_…`, `org:org_…` or `key:key_…`. An invitation to an address with no account is named by its `invitationId`, never its address.

Query parameter	Type	Required	Notes
`source`	`string`	No	up to 80 characters

Request body

Field	Type	Required	Notes
`rev`	`integer`	Yes	≥ 1
`preset`	`string`	No	up to 32 characters
`capabilities`	`string[]`	No	1–32 items; each up to 32 characters
`notBefore`	`integer`	No	> 0; can be `null`
`expiresAt`	`integer`	No	> 0; can be `null`
`schedule`	`object`	No	can be `null`
`schedule.tz`	`string`	Yes	1–64 characters
`schedule.windows`	`object[]`	Yes	1–8 items
`schedule.windows[].days`	`("sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat")[]`	Yes	1–7 items
`schedule.windows[].from`	`string`	Yes	up to 5 characters
`schedule.windows[].to`	`string`	Yes	up to 5 characters
`params`	`object`	No	keys up to 32 characters; values: string (up to 64 characters), number or boolean; can be `null`
`assistants`	`boolean`	No
`approval`	`string[]`	No	up to 32 items; each up to 32 characters; can be `null`
`includeGuests`	`boolean`	No
`notify`	`boolean`	No

Also checked: Unknown fields are rejected.

Response 200

{
  resource: string
  principal: string
  kind: "user" | "key" | "org" | "link" | "group" | "circle"
  name: null | string
  email: null | string
  deleted: boolean
  source: string
  status: "active" | "pending"
  capabilities: string[]
  preset: null | string
  notBefore: null | number
  expiresAt: null | number
  schedule: null | {
    tz: string
    windows: {
      days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
      from: string
      to: string
    }[]
  }
  params: null | {
    [key: string]: boolean | string | number
  }
  assistants: boolean
  approval: string[]
  includeGuests: boolean
  external: boolean
  blocked: null | string
  acceptBy: null | number
  pausedUntil: null | number
  grantedBy: {
    id: string
    name: null | string
  }
  createdAt: string
  updatedAt: string
  rev: number
}

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:write

Ends a grant, or withdraws an invitation, for those who may share the resource, and for the grantee leaving. ?source= picks one when a principal holds several; ?rev= makes it conditional (409 stale). The person is told unless ?notify=false. 204.

Auth: user access token or platform agent key

Path parameter	Description
`:rn`	A resource's name, `<app>:<type>:<id>` (`vehicles:vehicle:veh_…`), URL-encoded (`vehicles%3Avehicle%3Aveh_…`). The owner's space is read from the stored resource, never from the name.
`:principal`	Who a grant is to, URL-encoded: `user:usr_…`, `group:team_…`, `circle:cir_…`, `org:org_…` or `key:key_…`. An invitation to an address with no account is named by its `invitationId`, never its address.

Query parameter	Type	Required	Notes
`source`	`string`	No	up to 80 characters
`rev`	`integer`	No	≥ 1; coerced from a string
`notify`	`"true" \| "false"`	No

Response 204 with no body.

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:write

Pauses a grant made directly: { until } (epoch seconds in the future, or forever until it is resumed), with an optional rev. Paused, it gives only what stays on outside a schedule (a car's name and status, not where it is or whether it moves; a person's location gives nothing), and the grantee gets no notice; their requests answer 403 paused. For whoever may change the grant. Audited as share.pause.

Auth: user access token or platform agent key

Path parameter	Description
`:rn`	A resource's name, `<app>:<type>:<id>` (`vehicles:vehicle:veh_…`), URL-encoded (`vehicles%3Avehicle%3Aveh_…`). The owner's space is read from the stored resource, never from the name.
`:principal`	Who a grant is to, URL-encoded: `user:usr_…`, `group:team_…`, `circle:cir_…`, `org:org_…` or `key:key_…`. An invitation to an address with no account is named by its `invitationId`, never its address.

Request body

Field	Type	Required	Notes
`until`	`integer \| "forever"`	Yes	> 0, ≤ 253402300799
`rev`	`integer`	No	≥ 1

Also checked: Unknown fields are rejected.

Response 200

{
  resource: string
  principal: string
  kind: "user" | "key" | "org" | "link" | "group" | "circle"
  name: null | string
  email: null | string
  deleted: boolean
  source: string
  status: "active" | "pending"
  capabilities: string[]
  preset: null | string
  notBefore: null | number
  expiresAt: null | number
  schedule: null | {
    tz: string
    windows: {
      days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
      from: string
      to: string
    }[]
  }
  params: null | {
    [key: string]: boolean | string | number
  }
  assistants: boolean
  approval: string[]
  includeGuests: boolean
  external: boolean
  blocked: null | string
  acceptBy: null | number
  pausedUntil: null | number
  grantedBy: {
    id: string
    name: null | string
  }
  createdAt: string
  updatedAt: string
  rev: number
}

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:write

Resumes a paused grant at once. Audited as share.resume.

Auth: user access token or platform agent key

Path parameter	Description
`:rn`	A resource's name, `<app>:<type>:<id>` (`vehicles:vehicle:veh_…`), URL-encoded (`vehicles%3Avehicle%3Aveh_…`). The owner's space is read from the stored resource, never from the name.
`:principal`	Who a grant is to, URL-encoded: `user:usr_…`, `group:team_…`, `circle:cir_…`, `org:org_…` or `key:key_…`. An invitation to an address with no account is named by its `invitationId`, never its address.

Response 200

{
  resource: string
  principal: string
  kind: "user" | "key" | "org" | "link" | "group" | "circle"
  name: null | string
  email: null | string
  deleted: boolean
  source: string
  status: "active" | "pending"
  capabilities: string[]
  preset: null | string
  notBefore: null | number
  expiresAt: null | number
  schedule: null | {
    tz: string
    windows: {
      days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
      from: string
      to: string
    }[]
  }
  params: null | {
    [key: string]: boolean | string | number
  }
  assistants: boolean
  approval: string[]
  includeGuests: boolean
  external: boolean
  blocked: null | string
  acceptBy: null | number
  pausedUntil: null | number
  grantedBy: {
    id: string
    name: null | string
  }
  createdAt: string
  updatedAt: string
  rev: number
}

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:write

Withdraws an invitation to an address with no account, by its id (the address never goes in a URL), for its maker, the owner and role holders. 204.

Auth: user access token or platform agent key

Path parameter	Description
`:rn`	A resource's name, `<app>:<type>:<id>` (`vehicles:vehicle:veh_…`), URL-encoded (`vehicles%3Avehicle%3Aveh_…`). The owner's space is read from the stored resource, never from the name.
`:invitationId`	An invitation's id (`gin_…`), as `GET /v1/sharing/resources/:rn` lists it: a share waiting for an address with no account.

Response 204 with no body.

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:write

Makes a link to a resource: an audience (anyone, signed_in, or org for the owner organization's members), a preset or capabilities the type lets a link carry, an expiresAt within the longest the type allows, and an optional password. 201 with the link and its url, which is shown once and cannot be read again.

Auth: user access token or platform agent key

Path parameter	Description
`:rn`	A resource's name, `<app>:<type>:<id>` (`vehicles:vehicle:veh_…`), URL-encoded (`vehicles%3Avehicle%3Aveh_…`). The owner's space is read from the stored resource, never from the name.

Request body

Field	Type	Required	Notes
`audience`	`"anyone" \| "signed_in" \| "org"`	Yes
`preset`	`string`	No	up to 32 characters
`capabilities`	`string[]`	No	1–32 items; each up to 32 characters
`expiresAt`	`integer`	No	> 0
`password`	`string`	No	up to 128 characters

Also checked: Unknown fields are rejected.

Response 201

{
  link: {
    linkId: string
    resource: string
    audience: "org" | "anyone" | "signed_in"
    capabilities: string[]
    preset: null | string
    expiresAt: null | number
    passwordProtected: boolean
    blocked: null | string
    createdBy: {
      id: string
      name: null | string
    }
    createdAt: string
  }
  url: string
}

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:write

Ends a link and the access it gave. The person who made it, or anyone who may share the resource. 204; a link that isn't there (or isn't yours to see) is 404.

Auth: user access token or platform agent key

Path parameter	Description
`:linkId`	Link id (`ilk_…` for issue links, `irl_…` for remote links, `plk_…` for Photos links, `lnk_…` for sharing links and a drive's share links: not the link's secret).

Response 204 with no body.

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:write

Whether a person (principal=user:usr_…) holds a capability on the resource and where it comes from, for those who may share it and for holders of tenant:read in the owner organization. Nothing is audited: it is a question, not a use.

Auth: user access token or platform agent key

Path parameter	Description
`:rn`	A resource's name, `<app>:<type>:<id>` (`vehicles:vehicle:veh_…`), URL-encoded (`vehicles%3Avehicle%3Aveh_…`). The owner's space is read from the stored resource, never from the name.

Query parameter	Type	Required	Notes
`principal`	`string`	Yes	1–140 characters
`capability`	`string`	Yes	1–32 characters

Response 200

{
  allowed: boolean
  status: number
  code: null | string
  reason: null | string
  capabilities: string[]
  via: {
    kind: "role" | "owner" | "container"
    detail?: string
    capabilities: string[]
  } | {
    kind: "link" | "grant"
    resource: string
    inherited: boolean
    principal: string
    source: string
    preset?: string
    capabilities: string[]
    params?: {
      [key: string]: boolean | string | number
    }
    notBefore?: number
    expiresAt?: number
    schedule?: {
      tz: string
      windows: {
        days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
      }[]
    }
    approval?: string[]
    assistants?: boolean
    paused?: true
  }[]
}

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:read

`GET /v1/me/shared`

What is shared with you, your groups and your circles, newest first within a page (app, type, cursor, limit). Pages follow your principals one after another, so one can be short: carry on while cursor is set. The first page also turns invitations to your address into pending offers.

Auth: user access token or platform agent key

Query parameter	Type	Required	Notes
`app`	`string`	No	up to 32 characters
`type`	`string`	No	up to 32 characters
`cursor`	`string`	No	up to 2,000 characters
`limit`	`integer`	No	1–100; coerced from a string

Response 200

{
  items: {
    resource: string
    type: string
    app: string
    label: string
    owner: {
      spaceId: string
      kind: "org" | "personal"
      name: null | string
      you: boolean
    }
    via: {
      principal: string
      source: string
    }
    capabilities: string[]
    preset: null | string
    notBefore: null | number
    expiresAt: null | number
    schedule: null | {
      tz: string
      windows: {
        days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
      }[]
    }
    params: null | {
      [key: string]: boolean | string | number
    }
    grantedBy: {
      id: string
      name: null | string
    }
    createdAt: string
  }[]
  cursor: null | string
}

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:read

`GET /v1/me/shared/pending`

Offers waiting for you to accept (people outside your circles and organization share by offer), with what the owner can see of your use to read first (disclosure). They give nothing until accepted and lapse after 30 days.

Auth: user access token or platform agent key

Response 200

{
  items: {
    key: string
    resource: string
    type: string
    app: string
    label: string
    owner: {
      spaceId: string
      kind: "org" | "personal"
      name: null | string
      you: boolean
    }
    capabilities: string[]
    preset: null | string
    notBefore: null | number
    expiresAt: null | number
    schedule: null | {
      tz: string
      windows: {
        days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
      }[]
    }
    params: null | {
      [key: string]: boolean | string | number
    }
    approval: string[]
    acceptBy: number
    grantedBy: {
      id: string
      name: null | string
    }
    disclosure: null | string
    createdAt: string
    rev: number
  }[]
}

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:read

`POST /v1/me/shared/:grantKey/accept`

Accepts an offer: it becomes access, ending when the sharer said. 410 offer_lapsed once its 30 days ran out. Recorded in your log and the owner's.

Auth: user access token or platform agent key

Path parameter	Description
`:grantKey`	An offer's key, as `GET /v1/me/shared/pending` gives it (opaque).

Response 200

{
  resource: string
  type: string
  app: string
  label: string
  owner: {
    spaceId: string
    kind: "org" | "personal"
    name: null | string
    you: boolean
  }
  via: {
    principal: string
    source: string
  }
  capabilities: string[]
  preset: null | string
  notBefore: null | number
  expiresAt: null | number
  schedule: null | {
    tz: string
    windows: {
      days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
      from: string
      to: string
    }[]
  }
  params: null | {
    [key: string]: boolean | string | number
  }
  grantedBy: {
    id: string
    name: null | string
  }
  createdAt: string
}

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:write

`POST /v1/me/shared/:grantKey/decline`

Declines an offer; the sharer is told. 204.

Auth: user access token or platform agent key

Path parameter	Description
`:grantKey`	An offer's key, as `GET /v1/me/shared/pending` gives it (opaque).

Response 204 with no body.

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:write

What you share from your Personal space: the grants (newest first, paged by cursor) and, on the first page, your links.

Auth: user access token or platform agent key

Query parameter	Type	Required	Notes
`cursor`	`string`	No	up to 2,000 characters
`limit`	`integer`	No	1–100; coerced from a string

Response 200

{
  grants: {
    resource: string
    principal: string
    kind: "user" | "key" | "org" | "link" | "group" | "circle"
    name: null | string
    email: null | string
    deleted: boolean
    source: string
    status: "active" | "pending"
    capabilities: string[]
    preset: null | string
    notBefore: null | number
    expiresAt: null | number
    schedule: null | {
      tz: string
      windows: {
        days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
      }[]
    }
    params: null | {
      [key: string]: boolean | string | number
    }
    assistants: boolean
    approval: string[]
    includeGuests: boolean
    external: boolean
    blocked: null | string
    acceptBy: null | number
    pausedUntil: null | number
    grantedBy: {
      id: string
      name: null | string
    }
    createdAt: string
    updatedAt: string
    rev: number
  }[]
  links: {
    linkId: string
    resource: string
    audience: "org" | "anyone" | "signed_in"
    capabilities: string[]
    preset: null | string
    expiresAt: null | number
    passwordProtected: boolean
    blocked: null | string
    createdBy: {
      id: string
      name: null | string
    }
    createdAt: string
  }[]
  cursor: null | string
}

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:read

`GET /v1/me/shared`

Auth: user access token or platform agent key

Query parameter	Type	Required	Notes
`app`	`string`	No	up to 32 characters
`type`	`string`	No	up to 32 characters
`cursor`	`string`	No	up to 2,000 characters
`limit`	`integer`	No	1–100; coerced from a string

Response 200

{
  items: {
    resource: string
    type: string
    app: string
    label: string
    owner: {
      spaceId: string
      kind: "org" | "personal"
      name: null | string
      you: boolean
    }
    via: {
      principal: string
      source: string
    }
    capabilities: string[]
    preset: null | string
    notBefore: null | number
    expiresAt: null | number
    schedule: null | {
      tz: string
      windows: {
        days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
      }[]
    }
    params: null | {
      [key: string]: boolean | string | number
    }
    grantedBy: {
      id: string
      name: null | string
    }
    createdAt: string
  }[]
  cursor: null | string
}

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:read

`GET /v1/me/shared/pending`

Auth: user access token or platform agent key

Response 200

{
  items: {
    key: string
    resource: string
    type: string
    app: string
    label: string
    owner: {
      spaceId: string
      kind: "org" | "personal"
      name: null | string
      you: boolean
    }
    capabilities: string[]
    preset: null | string
    notBefore: null | number
    expiresAt: null | number
    schedule: null | {
      tz: string
      windows: {
        days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
      }[]
    }
    params: null | {
      [key: string]: boolean | string | number
    }
    approval: string[]
    acceptBy: number
    grantedBy: {
      id: string
      name: null | string
    }
    disclosure: null | string
    createdAt: string
    rev: number
  }[]
}

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:read

`POST /v1/me/shared/:grantKey/accept`

Accepts an offer: it becomes access, ending when the sharer said. 410 offer_lapsed once its 30 days ran out. Recorded in your log and the owner's.

Auth: user access token or platform agent key

Path parameter	Description
`:grantKey`	An offer's key, as `GET /v1/me/shared/pending` gives it (opaque).

Response 200

{
  resource: string
  type: string
  app: string
  label: string
  owner: {
    spaceId: string
    kind: "org" | "personal"
    name: null | string
    you: boolean
  }
  via: {
    principal: string
    source: string
  }
  capabilities: string[]
  preset: null | string
  notBefore: null | number
  expiresAt: null | number
  schedule: null | {
    tz: string
    windows: {
      days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
      from: string
      to: string
    }[]
  }
  params: null | {
    [key: string]: boolean | string | number
  }
  grantedBy: {
    id: string
    name: null | string
  }
  createdAt: string
}

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:write

`POST /v1/me/shared/:grantKey/decline`

Declines an offer; the sharer is told. 204.

Auth: user access token or platform agent key

Path parameter	Description
`:grantKey`	An offer's key, as `GET /v1/me/shared/pending` gives it (opaque).

Response 204 with no body.

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:write

What you share from your Personal space: the grants (newest first, paged by cursor) and, on the first page, your links.

Auth: user access token or platform agent key

Query parameter	Type	Required	Notes
`cursor`	`string`	No	up to 2,000 characters
`limit`	`integer`	No	1–100; coerced from a string

Response 200

{
  grants: {
    resource: string
    principal: string
    kind: "user" | "key" | "org" | "link" | "group" | "circle"
    name: null | string
    email: null | string
    deleted: boolean
    source: string
    status: "active" | "pending"
    capabilities: string[]
    preset: null | string
    notBefore: null | number
    expiresAt: null | number
    schedule: null | {
      tz: string
      windows: {
        days: ("sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat")[]
        from: string
        to: string
      }[]
    }
    params: null | {
      [key: string]: boolean | string | number
    }
    assistants: boolean
    approval: string[]
    includeGuests: boolean
    external: boolean
    blocked: null | string
    acceptBy: null | number
    pausedUntil: null | number
    grantedBy: {
      id: string
      name: null | string
    }
    createdAt: string
    updatedAt: string
    rev: number
  }[]
  links: {
    linkId: string
    resource: string
    audience: "org" | "anyone" | "signed_in"
    capabilities: string[]
    preset: null | string
    expiresAt: null | number
    passwordProtected: boolean
    blocked: null | string
    createdBy: {
      id: string
      name: null | string
    }
    createdAt: string
  }[]
  cursor: null | string
}

Errors

Status	Message
`403`	Sharing isn't available to the phone assistant.
`403`	Sharing is changed by you, not by the assistant.
`403`	Name the chat's space in x-si-org: an organisation or personal.
`403`	You aren't a member of that organisation.
`403`	Sharing needs a signed-in person or an organisation's key.
`403`	Missing scope sharing:read

Sharing

On this page