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

# List Assets

> List the calling user's assets (hosted sites, storage bundles, and managed skill folders). Optionally filter by status, privacy, owner, or a search string, and page through results with limit/offset.



## OpenAPI

````yaml get /api/v2/asset/list
openapi: 3.0.0
info:
  version: 1.0.0
  title: Octave API
  description: API for Octave workspace management and AI-powered content generation
servers:
  - url: https://app.octavehq.com
security:
  - ApiKeyAuth: []
paths:
  /api/v2/asset/list:
    get:
      tags:
        - Asset
      summary: List Assets
      description: >-
        List the calling user's assets (hosted sites, storage bundles, and
        managed skill folders). Optionally filter by status, privacy, owner, or
        a search string, and page through results with limit/offset.
      operationId: listAssets
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
            description: Max assets to return, 1–100. e.g. 20
          required: false
          description: Max assets to return, 1–100. e.g. 20
          name: limit
          in: query
        - schema:
            type: integer
            nullable: true
            minimum: 0
            default: 0
            description: How many assets to skip, for pagination. e.g. 0
          required: false
          description: How many assets to skip, for pagination. e.g. 0
          name: offset
          in: query
        - schema:
            type: string
            enum:
              - published
              - unpublished
            description: >-
              Filter by lifecycle status; omit for all. One of: published,
              unpublished. e.g. 'published'
          required: false
          description: >-
            Filter by lifecycle status; omit for all. One of: published,
            unpublished. e.g. 'published'
          name: status
          in: query
        - schema:
            type: string
            enum:
              - only_me
              - workspace
              - public
            description: >-
              Filter by privacy; omit for all. One of: only_me, workspace,
              public. e.g. 'public'
          required: false
          description: >-
            Filter by privacy; omit for all. One of: only_me, workspace, public.
            e.g. 'public'
          name: privacy
          in: query
        - schema:
            type: string
            maxLength: 255
            description: >-
              Server-side case-insensitive substring match across identifier,
              description, and vanitySlug — use this to check whether something
              is already published before creating it. Applied before
              pagination, so total reflects matches. e.g. 'q3 deck'
          required: false
          description: >-
            Server-side case-insensitive substring match across identifier,
            description, and vanitySlug — use this to check whether something is
            already published before creating it. Applied before pagination, so
            total reflects matches. e.g. 'q3 deck'
          name: search
          in: query
        - schema:
            type: string
            format: email
            description: >-
              Only assets owned by this workspace member (within what you can
              already see — never widens access). e.g. 'sam@acme.com'
          required: false
          description: >-
            Only assets owned by this workspace member (within what you can
            already see — never widens access). e.g. 'sam@acme.com'
          name: ownerEmail
          in: query
      responses:
        '200':
          description: Assets listed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Asset'
                  total:
                    type: number
                  hasNext:
                    type: boolean
                required:
                  - _metadata
                  - data
                  - total
                  - hasNext
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
                required:
                  - _metadata
      deprecated: false
components:
  schemas:
    Metadata:
      type: object
      properties:
        usage:
          type: number
          default: 0
          example: 0
          description: API usage
        requestId:
          type: string
          example: requestId
          description: Request ID
        message:
          type: string
          example: message
          description: Message
        timestamp:
          type: string
          example: '2021-01-01T00:00:00.000Z'
          description: Timestamp
      required:
        - requestId
        - timestamp
    Asset:
      type: object
      properties:
        uuid:
          type: string
          description: >-
            Asset UUID — the id used by every asset_* tool. e.g.
            '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'
        identifier:
          type: string
          description: Human-readable identifier/slug. e.g. 'q3-launch-microsite'
        description:
          type: string
          description: Free-text description. e.g. 'Q3 product launch landing page'
        type:
          type: string
          enum:
            - website
            - storage
            - skill
          description: >-
            Kind of asset. One of: website (served as a hosted site), storage
            (downloadable files), skill (Agent Skill folder — managed via the
            skill tools). e.g. 'website'
        entryPoint:
          type: string
          nullable: true
          description: >-
            File served at the site root; null for storage assets. e.g.
            'index.html'
        storagePath:
          type: string
          nullable: true
          description: >-
            Internal storage path; null until files are stored. e.g.
            'workspaces/ws_1/assets/4f1e2a90'
        currentVersion:
          type: number
          description: >-
            Version the asset's URL serves right now; changes on file updates
            and on asset_version_restore. e.g. 3
        latestVersion:
          type: number
          description: >-
            Highest version ever minted (the high-water mark) — greater than
            currentVersion after a rollback. e.g. 4
        vanitySlug:
          type: string
          nullable: true
          description: >-
            Workspace-unique vanity slug, set via asset_update; null when the
            asset has none. e.g. 'q3-launch'
        vanityUrl:
          type: string
          nullable: true
          description: >-
            Friendly URL built from the workspace's vanity handle + vanitySlug;
            null until a slug is set. e.g.
            'https://sites.octave.app/s/acme/q3-launch/'
        siteUrl:
          type: string
          nullable: true
          description: >-
            Public URL of the served site; null until published. e.g.
            'https://sites.octave.app/4f1e2a90'
        previewUrl:
          type: string
          nullable: true
          description: >-
            Tokenized link to preview this asset while it isn't publicly
            servable yet (privacy is only_me/workspace, or status is
            unpublished) — the owner or a workspace teammate can open it even
            though the public URL 404s. null once published + public (use
            siteUrl). e.g. 'https://sites.octave.app/preview/eyJ...'
        thumbnailUrl:
          type: string
          nullable: true
          description: >-
            Screenshot of the site, gated like the asset itself: a plain URL
            once published + public, tokenized otherwise. Null is normal —
            storage assets never have one, website screenshots are rendered
            asynchronously after upload, and a failed render stays null. e.g.
            'https://sites.octave.app/thumbnails/4f1e2a90.jpg'
        status:
          type: string
          enum:
            - published
            - unpublished
          description: >-
            Lifecycle status. One of: published (default; discoverable),
            unpublished (hidden, still readable by uuid). Independent of privacy
            — publishing does NOT make an asset public; set privacy to 'public'
            for that. e.g. 'published'
        privacy:
          type: string
          enum:
            - only_me
            - workspace
            - public
          description: >-
            Who can access it — an ordered ladder, each tier strictly more
            permissive: only_me (owner only), workspace (default; owner +
            workspace members), public (anyone with the URL). e.g. 'workspace'
        externallyShared:
          type: boolean
          description: >-
            Derived, read-only: true when privacy isn't public and the asset has
            at least one active share link (i.e. it's shared with specific
            people/domains outside the workspace). Creating/revoking a share
            link changes this, not asset_update. e.g. false
        openLink:
          type: boolean
          description: >-
            Derived, read-only: true when privacy isn't public and at least one
            active share link admits ANYONE holding it (access: 'anyone'). The
            sharper half of externallyShared — that says some outsiders can see
            this, this says anyone with the URL can, which the privacy tier
            alone would hide. Report it wherever you report the tier. e.g. false
        owner:
          type: string
          description: >-
            Who owns the asset, from your perspective: 'me' for your own assets,
            otherwise the owner's 'First Last <email>' (a workspace teammate).
            e.g. 'me'
        ownerEmail:
          type: string
          nullable: true
          description: >-
            The owner's email as a structured field — always the real identity,
            even when `owner` reads 'me'. Null only for assets created before
            owner-identity capture. e.g. 'ada@acme.com'
        metadata:
          type: object
          properties:
            filesMap:
              type: array
              items:
                type: object
                properties:
                  filename:
                    type: string
                    description: File name. e.g. 'index.html'
                  size:
                    type: number
                    description: File size in bytes. e.g. 20480
                  mimeType:
                    type: string
                    description: MIME type. e.g. 'text/html'
                  path:
                    type: string
                    description: Path within the asset. e.g. '/index.html'
                  createdAt:
                    type: string
                    description: >-
                      ISO-8601 time the file was stored. e.g.
                      '2026-07-03T10:15:00.000Z'
                required:
                  - filename
                  - size
                  - mimeType
                  - path
                  - createdAt
              description: Flat list of every file in the asset.
            siteMap:
              type: object
              nullable: true
              properties:
                totalFiles:
                  type: number
                  description: Total number of files in the site. e.g. 12
                totalSize:
                  type: number
                  description: Total size of the site in bytes. e.g. 348160
                entryPoint:
                  type: string
                  description: File served at the site root. e.g. 'index.html'
                root:
                  $ref: '#/components/schemas/AssetSiteMapDirNode'
              required:
                - totalFiles
                - totalSize
                - entryPoint
                - root
              description: Directory tree of the site; null if not yet computed.
          required:
            - filesMap
            - siteMap
          description: File metadata for the asset.
        skillMetadata:
          type: object
          nullable: true
          properties:
            name:
              type: string
            description:
              type: string
          required:
            - name
            - description
          description: >-
            Parsed SKILL.md frontmatter — only set for skill-type artifacts;
            null otherwise.
        createdAt:
          type: string
          description: ISO-8601 creation time. e.g. '2026-07-01T09:00:00.000Z'
        updatedAt:
          type: string
          description: ISO-8601 last-update time. e.g. '2026-07-03T12:30:00.000Z'
      required:
        - uuid
        - identifier
        - description
        - type
        - entryPoint
        - storagePath
        - currentVersion
        - latestVersion
        - vanitySlug
        - vanityUrl
        - siteUrl
        - previewUrl
        - thumbnailUrl
        - status
        - privacy
        - externallyShared
        - openLink
        - owner
        - ownerEmail
        - metadata
        - skillMetadata
        - createdAt
        - updatedAt
    AssetSiteMapDirNode:
      type: object
      properties:
        type:
          type: string
          enum:
            - dir
        name:
          type: string
          description: Directory name. e.g. 'assets'
        path:
          type: string
          description: Directory path. e.g. '/assets'
        fileCount:
          type: number
          description: Number of files under this directory, recursive. e.g. 8
        totalSize:
          type: number
          description: Total bytes under this directory, recursive. e.g. 51200
        children:
          type: array
          items:
            anyOf:
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - file
                  name:
                    type: string
                    description: File name. e.g. 'index.html'
                  path:
                    type: string
                    description: Path within the asset. e.g. '/assets/app.js'
                  size:
                    type: number
                    description: File size in bytes. e.g. 4096
                  mimeType:
                    type: string
                    description: MIME type. e.g. 'text/javascript'
                  isEntryPoint:
                    type: boolean
                    description: True if this file is the site's entry point. e.g. false
                required:
                  - type
                  - name
                  - path
                  - size
                  - mimeType
                  - isEntryPoint
              - $ref: '#/components/schemas/AssetSiteMapDirNode'
          description: Child files and subdirectories.
      required:
        - type
        - name
        - path
        - fileCount
        - totalSize
        - children
      description: Root node of the site's directory tree.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api_key

````