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

# List apps

> Returns the workspace's catalog of persistent app surfaces, visible to any member of
the workspace, excluding destroyed apps and ordered by most recent activity. Each
app includes its id, slug, state, visibility (public or private), run mode, declared
port, originating conversation id (null if that conversation was deleted), a
ready-to-open visitor URL, and creation/last-activity timestamps. Also returns the
workspace's app quota and how many apps currently count against it.



## OpenAPI

````yaml GET /v1/api/apps
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/apps:
    get:
      tags:
        - conversations
      summary: List apps
      description: >-
        Returns the workspace's catalog of persistent app surfaces, visible to
        any member of

        the workspace, excluding destroyed apps and ordered by most recent
        activity. Each

        app includes its id, slug, state, visibility (public or private), run
        mode, declared

        port, originating conversation id (null if that conversation was
        deleted), a

        ready-to-open visitor URL, and creation/last-activity timestamps. Also
        returns the

        workspace's app quota and how many apps currently count against it.
      operationId: list_apps
      responses:
        '200':
          description: Workspace app catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppsResp'
      security:
        - bearer_pat:
            - conversations:read
        - oauth2:
            - conversations:read
components:
  schemas:
    AppsResp:
      type: object
      required:
        - apps
        - max_persistent
        - used
      properties:
        apps:
          type: array
          items:
            $ref: '#/components/schemas/AppLite'
        max_persistent:
          type: integer
          format: int32
          description: >-
            The apps quota - plan-driven (`plan.max_apps`) with a fallback to
            the

            legacy `tenants.max_persistent_surfaces` - and how many
            non-destroyed

            apps count against it. Drives the "N of M slots used" line.
        used:
          type: integer
          minimum: 0
    AppLite:
      type: object
      required:
        - id
        - slug
        - state
        - visibility
        - run_mode
        - declared_port
        - url
        - created_at
        - last_activity_at
      properties:
        backing_conversation_id:
          type:
            - string
            - 'null'
          format: uuid
          description: |-
            The conversation that authored the app - lets the UI deep-link
            to the Studio thread. `None` if the backing conv was deleted.
        created_at:
          type: integer
          format: int64
          description: Unix seconds - the UI humanises ("2 days ago").
        declared_port:
          type: integer
          format: int32
        id:
          type: string
          format: uuid
        last_activity_at:
          type: integer
          format: int64
        run_mode:
          type: string
        slug:
          type: string
        state:
          type: string
        url:
          type: string
          description: |-
            Visitor-facing URL (bare for public, signed plain-host for
            private). Empty-ish only when no HMAC secret is loaded.
        visibility:
          type: string
          description: |-
            "public" | "private" - derived from `auth_mode`. The surfaces
            table has no `visibility` column; public == `auth_mode='public'`.
  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

````