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

# Delete a conversation

> Permanently deletes a conversation and cascades teardown of its backing app
surfaces, sandbox resources, messages, and related records. Scoped to the caller's
workspace and conversations they participate in. By default the conversation's
delivered artifacts are detached and kept (still downloadable by their existing
links); passing delete_artifacts=true permanently deletes those artifacts instead.
Returns the conversation id along with counts of apps destroyed and artifacts
deleted versus kept. Returns 404 if not found.



## OpenAPI

````yaml DELETE /v1/api/conversations/{id}
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/conversations/{id}:
    delete:
      tags:
        - conversations
      summary: Delete a conversation
      description: >-
        Permanently deletes a conversation and cascades teardown of its backing
        app

        surfaces, sandbox resources, messages, and related records. Scoped to
        the caller's

        workspace and conversations they participate in. By default the
        conversation's

        delivered artifacts are detached and kept (still downloadable by their
        existing

        links); passing delete_artifacts=true permanently deletes those
        artifacts instead.

        Returns the conversation id along with counts of apps destroyed and
        artifacts

        deleted versus kept. Returns 404 if not found.
      operationId: delete_conversation
      parameters:
        - name: id
          in: path
          description: Conversation id
          required: true
          schema:
            type: string
            format: uuid
        - name: delete_artifacts
          in: query
          description: |-
            `true` also permanently deletes the conversation's delivered
            artifacts (blobs + rows). Default `false` - keep them (detach).
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: Conversation deleted (cascade)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteConvResp'
        '404':
          description: Not found
      security:
        - bearer_pat:
            - conversations:write
        - oauth2:
            - conversations:write
components:
  schemas:
    DeleteConvResp:
      type: object
      required:
        - conversation_id
        - apps_destroyed
        - artifacts_deleted
        - artifacts_kept
      properties:
        apps_destroyed:
          type: integer
          minimum: 0
        artifacts_deleted:
          type: integer
          description: |-
            Delivered artifacts whose Trove blobs + rows were deleted (when
            the caller asked to delete them).
          minimum: 0
        artifacts_kept:
          type: integer
          description: |-
            Delivered artifacts detached (`conversation_id` -> NULL) and kept
            in Trove - the default. They survive the conversation, still
            downloadable by their existing `/v1/api/artifacts/{id}/download`
            link, just no longer tied to a (now-deleted) conversation.
          minimum: 0
        conversation_id:
          type: string
          format: uuid
  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

````