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

# List Vault Projects and Knowledge Bases

> Lists all Vault projects and knowledge bases in the current workspace with pagination support. This endpoint returns a paginated list of projects that the authenticated user has permission to view.

### Permissions

Requires `View workspace projects` permission.


## OpenAPI

````yaml /vault_api.json get /api/v1/vault/workspace/projects
openapi: 3.0.1
info:
  title: Vault - Upload Documents
  description: >-
    The Vault Upload Documents API enables users to programmatically upload and
    manage documents within Vault projects. This API allows organizations to
    maintain projects with their own internal files for their users to use
    within the Harvey app.
  version: 1.0.0
  contact:
    email: support@harvey.ai
servers:
  - url: https://api.harvey.ai
    description: Harvey API server
security: []
paths:
  /api/v1/vault/workspace/projects:
    get:
      tags:
        - Vault
      summary: List Vault Projects and Knowledge Bases
      description: >-
        Lists all Vault projects and knowledge bases in the current workspace
        with pagination support. This endpoint returns a paginated list of
        projects that the authenticated user has permission to view.
      operationId: listWorkspaceProjects
      parameters:
        - name: page
          in: query
          description: 'Page number for pagination (default: 1)'
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          description: 'Number of items per page (default: 20, max: 100)'
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: name
          in: query
          description: Case-insensitive substring match on project name.
          schema:
            type: string
            maxLength: 256
          example: acme
        - name: is_knowledge_base
          in: query
          description: >-
            Filter by knowledge base flag. `true` returns only knowledge base
            projects, `false` excludes them, and omitting the parameter returns
            both.
          schema:
            type: boolean
        - name: created_after
          in: query
          description: >-
            Inclusive lower bound on project creation time, expressed as a UTC
            Unix epoch timestamp in seconds. Only projects with `created_at >=
            created_after` are returned. Must be strictly less than
            `created_before` when both are provided.
          schema:
            type: integer
            format: int64
          example: 1767225600
        - name: created_before
          in: query
          description: >-
            Exclusive upper bound on project creation time, expressed as a UTC
            Unix epoch timestamp in seconds. Only projects with `created_at <
            created_before` are returned.
          schema:
            type: integer
            format: int64
          example: 1775347200
        - name: sort_by
          in: query
          description: >-
            Field to sort the results by. `date` sorts by the project's last
            content-update timestamp (the default ordering). `name` sorts
            alphabetically by project name.
          schema:
            type: string
            enum:
              - date
              - name
            default: date
        - name: sort_order
          in: query
          description: Sort direction to order results list.
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: Successfully retrieved workspace projects
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      content:
                        type: object
                        properties:
                          projects:
                            type: array
                            items:
                              $ref: '#/components/schemas/Project'
                            description: Array of projects in the workspace
                          pagination:
                            type: object
                            properties:
                              page:
                                type: integer
                                description: Current page number
                                example: 3
                              per_page:
                                type: integer
                                description: Number of items per page
                                example: 20
                              total:
                                type: integer
                                description: Total number of projects
                                example: 45
                              total_pages:
                                type: integer
                                description: Total number of pages
                                example: 3
              examples:
                listWorkspaceProjects:
                  summary: Example response for listing workspace projects
                  value:
                    response:
                      content:
                        pagination:
                          page: 1
                          per_page: 20
                          total: 150
                          total_pages: 8
                        projects:
                          - created_at: '2024-01-15T10:30:00.000000'
                            creator_email: user@example.com
                            files_count: 109
                            id: 12345678-1234-5678-1234-567812345678
                            is_knowledge_base_project: false
                            name: Example Legal Project
                            project_retained_at: '2027-01-20T14:45:00.000000'
                            project_updated_at: '2026-01-20T14:45:00.000000'
                            query_count: 30
                            sharing:
                              user_count: 0
                              user_shares: []
                              workspace_count: 0
                              workspace_shares: []
                            size_bytes: 104857600
                            updated_at: '2024-01-20T14:45:00.000000'
                          - created_at: '2024-01-10T09:15:00.000000'
                            creator_email: user@example.com
                            files_count: 45
                            id: 87654321-8765-4321-8765-432187654321
                            is_knowledge_base_project: true
                            name: Knowledge Base Project
                            project_updated_at: '2026-01-18T11:20:00.000000'
                            query_count: 15
                            sharing:
                              user_count: 2
                              user_shares:
                                - created_at: '2024-01-16T13:45:00.000000'
                                  dest_user_email: collaborator@example.com
                                  dest_user_id: 11111111-2222-3333-4444-555566667777
                                  dest_workspace_id: 2
                                  permission_level: VIEW
                                  src_user_id: 12345678-1234-5678-1234-567812345678
                                  src_workspace_id: 1
                                  vault_folder_id: 87654321-8765-4321-8765-432187654321
                              workspace_count: 1
                              workspace_shares:
                                - created_at: '2024-01-17T16:30:00.000000'
                                  dest_workspace_id: 3
                                  permission_level: EDIT
                                  src_user_id: 12345678-1234-5678-1234-567812345678
                                  src_workspace_id: 1
                                  vault_folder_id: 87654321-8765-4321-8765-432187654321
                            size_bytes: 52428800
                            updated_at: '2024-01-18T11:20:00.000000'
        '400':
          description: >-
            Bad request - Invalid query parameters (e.g. `page < 1`, `per_page >
            100`, malformed `created_after`/`created_before`, `created_after >=
            created_before`, or unrecognized `sort_by`/`sort_order` value)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid query parameters
                  details:
                    type: array
                    description: Per-field validation errors
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          description: Name of the query parameter that failed validation
                          example: created_before
                        message:
                          type: string
                          description: Human-readable description of the validation failure
                          example: created_after must be earlier than created_before
        '401':
          description: Unauthorized - Invalid or missing API token
        '403':
          description: Forbidden - User does not have permission to view workspace projects
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal server error
      security:
        - bearerAuth: []
components:
  schemas:
    Project:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the project
          example: abcdef12-3456-7890-abcd-ef1234567890
        name:
          type: string
          description: The name of the project
          example: Sample Contract Repository
        client_matter_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            The associated client matter UUID (not the human-readable matter
            number)
          example: 11111111-2222-3333-4444-555555555555
        created_at:
          type: string
          format: date-time
          description: Timestamp when the project was created
          example: '2024-12-04T01:22:03.584677'
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the project metadata was last updated
          example: '2025-03-25T14:49:45.612193'
        project_updated_at:
          type: string
          format: date-time
          description: Timestamp when the project content was last updated
          example: '2025-02-14T19:29:50.549982'
        project_retained_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Timestamp when the vault project is retained. This date can be in
            the future. This field is only present in the response when it is
            non-null; it is omitted when the project has no retention timestamp
            set.
          example: '2026-02-14T19:29:50.549982'
        creator_email:
          type: string
          format: email
          description: Email of the user who created the project
          example: user@example.com
        is_knowledge_base_project:
          type: boolean
          description: Whether this project is designated as a knowledge base
          example: false
        files_count:
          type: integer
          description: Number of files in the project
          example: 4
        size_bytes:
          type: integer
          description: Total size of all files in bytes
          example: 5325148
        query_count:
          type: integer
          description: Number of queries made against this project
          example: 0
        sharing:
          type: object
          description: Sharing information for the project
          properties:
            user_count:
              type: integer
              description: Number of users the project is shared with
              example: 0
            user_shares:
              type: array
              items:
                $ref: '#/components/schemas/ShareDetails'
              description: List of user share details
            workspace_count:
              type: integer
              description: Number of workspaces the project is shared with
              example: 1
            workspace_shares:
              type: array
              items:
                $ref: '#/components/schemas/ShareDetails'
              description: List of workspace share details
    ShareDetails:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
          description: When the share was created
          example: '2024-01-16T13:45:00.000000'
        dest_user_email:
          type: string
          format: email
          description: Email of the destination user (for user shares)
          example: collaborator@example.com
        dest_user_id:
          type: string
          format: uuid
          description: ID of the destination user (for user shares)
          example: 11111111-2222-3333-4444-555566667777
        dest_workspace_id:
          type: integer
          description: Destination workspace ID
          example: 2
        permission_level:
          type: string
          enum:
            - VIEW
            - EDIT
            - ADMIN
          description: Permission level for the share
          example: VIEW
        src_user_id:
          type: string
          format: uuid
          description: Source user ID who created the share
          example: 12345678-1234-5678-1234-567812345678
        src_workspace_id:
          type: integer
          description: Source workspace ID
          example: 1
        vault_folder_id:
          type: string
          format: uuid
          description: The vault folder/project ID being shared
          example: 87654321-8765-4321-8765-432187654321
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````