Share a surface

curl --request POST \
  --url https://api.hq.zone/v1/api/surfaces/{id}/share \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ttl_secs": 123
}
'

{
  "exp": 123,
  "surface_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "url": "<string>"
}

Conversations

Share a surface

Mints a time-limited signed share URL for an app surface that the caller can hand out, without making the surface publicly visible. Scoped to the caller’s workspace, and the caller must be able to access the surface’s backing conversation. The optional ttl_secs sets the validity window, defaulting to 7 days and constrained to between 1 minute and 30 days (out-of-range values are rejected). Returns the surface id, the tokenized URL, and its expiry as a Unix timestamp. Returns 404 if the surface is not found.

POST

api

surfaces

{id}

Share a surface

curl --request POST \
  --url https://api.hq.zone/v1/api/surfaces/{id}/share \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ttl_secs": 123
}
'

{
  "exp": 123,
  "surface_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "url": "<string>"
}

Authorizations

Authorization

string

header

required

Personal Access Token. Send as Authorization: Bearer hq_pat_....

Path Parameters

string<uuid>

required

Surface id

Body

application/json

ttl_secs

integer<int64> | null

Seconds the signed URL stays valid for. None defaults to 7 days; clamped to the [1 min, 30 day] inclusive range. Anything outside that range is rejected so a typo in the SPA can't mint a year-long link.

Response

Time-limited signed share URL

exp

integer<int64>

required

Unix-ts seconds; the SPA renders "expires …" using this.

surface_id

string<uuid>

required

url

string

required

Tokenized URL the user copies. Valid until exp.

List conversation surfaces Set surface visibility

⌘I