> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hq.zone/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.



## OpenAPI

````yaml POST /v1/api/surfaces/{id}/share
openapi: 3.1.0
info:
  title: HQ API
  description: >-
    Public HTTP API for HQ. Authenticate with a Personal Access Token
    (`Authorization: Bearer hq_pat_...`) for server-side integrations, or an
    OAuth 2.1 authorization-code + PKCE flow for browser apps acting on a user's
    behalf. Both grant from the same resource:action scope vocabulary; an
    endpoint's required scope is listed under its `security`.
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  version: 1.0.0
servers:
  - url: https://api.hq.zone
    description: HQ API (production)
security: []
tags:
  - name: me
    description: The signed-in user's own account
  - name: conversations
    description: Conversations and their messages
  - name: documents
    description: The content-addressed documents library
  - name: schedules
    description: Scheduled prompts and recurring tasks
  - name: agents
    description: Agents, their skills and integrations
  - name: memory
    description: What the assistant remembers (L5 governance)
  - name: tokens
    description: Personal Access Token management
  - name: billing
    description: Usage and billing
  - name: notifications
    description: In-app notification center
  - name: admin
    description: Workspace administration
  - name: integrations
    description: Workspace integrations (Slack, MCP, skills)
  - name: onboarding
    description: New-workspace onboarding wizard
  - name: auth
    description: Sign-in, sessions, and OAuth
paths:
  /v1/api/surfaces/{id}/share:
    post:
      tags:
        - conversations
      summary: Share a surface
      description: >-
        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.
      operationId: share_surface
      parameters:
        - name: id
          in: path
          description: Surface id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareReq'
        required: true
      responses:
        '200':
          description: Time-limited signed share URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareResp'
        '404':
          description: Surface not found
      security:
        - bearer_pat:
            - conversations:write
        - oauth2:
            - conversations:write
components:
  schemas:
    ShareReq:
      type: object
      properties:
        ttl_secs:
          type:
            - integer
            - 'null'
          format: int64
          description: |-
            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.
    ShareResp:
      type: object
      required:
        - surface_id
        - url
        - exp
      properties:
        exp:
          type: integer
          format: int64
          description: Unix-ts seconds; the SPA renders "expires …" using this.
        surface_id:
          type: string
          format: uuid
        url:
          type: string
          description: Tokenized URL the user copies. Valid until `exp`.
  securitySchemes:
    bearer_pat:
      type: http
      scheme: bearer
      bearerFormat: hq_pat
      description: 'Personal Access Token. Send as `Authorization: Bearer hq_pat_...`.'
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hq.zone/v1/oauth/authorize
          tokenUrl: https://api.hq.zone/v1/oauth/token
          refreshUrl: https://api.hq.zone/v1/oauth/token
          scopes:
            admin: Administer the workspace (users, settings, integrations)
            agents:read: View the agents in your workspace
            agents:write: Create and configure agents
            billing:read: View usage and billing information
            conversations:read: Read your conversations and their messages
            conversations:write: Start conversations and send messages on your behalf
            documents:read: Read your documents library
            documents:write: Upload and manage documents in your library
            memory:read: Read what the assistant remembers about you
            memory:write: Correct or delete what the assistant remembers
            schedules:read: View your scheduled tasks
            schedules:write: Create and manage scheduled tasks
            tables:read: Read your tables and their rows
            tables:write: Create tables and add, edit, or delete rows

````