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

# List Project-Scope Knowledge

> List the knowledge files stored under the project's project/ prefix only. These files are visible to every run in the project.

<Info>
  **Permission Required**: any API key scoped to the requested project
</Info>

<Note>
  Knowledge endpoints are served by the **bouncer** service at
  `https://bouncer.nunu.ai`, not the main `nunu.ai/api/v1` host. Use the same
  `X-Api-Key` header for authentication.
</Note>

Returns only the files stored under the project's `project/` prefix. These are
the files that every run in the project sees regardless of which agent or test
case it executes.

If you instead want a single response that combines project files with
agent- or test-case-scoped files, use
[List Knowledge Files](/api-reference/knowledge/list-files).

## Path Parameters

<ParamField path="projectId" type="string" required>
  The nunu.ai project ID. Must match the project the API key is scoped to.
</ParamField>

## Query Parameters

<ParamField query="include_metadata" type="boolean" default="false">
  When `true`, attach parsed metadata (`description`, `summary`, `keywords`)
  for each file from its `.{name}.meta.json` sidecar.
</ParamField>

## Response

<ResponseField name="projectId" type="string" required>
  Echo of the path parameter.
</ResponseField>

<ResponseField name="scope" type="string" required>
  Always `"project"` for this endpoint.
</ResponseField>

<ResponseField name="count" type="integer" required>
  Number of files returned.
</ResponseField>

<ResponseField name="files" type="File[]" required>
  Files in the project scope.

  <Expandable title="File properties">
    <ResponseField name="files[].filename" type="string">
      Basename of the file.
    </ResponseField>

    <ResponseField name="files[].path" type="string">
      Path relative to the scope root (may include subdirectories).
    </ResponseField>

    <ResponseField name="files[].size" type="integer">
      Size in bytes.
    </ResponseField>

    <ResponseField name="files[].uploaded" type="string">
      ISO 8601 timestamp when the file was last written.
    </ResponseField>

    <ResponseField name="files[].etag" type="string">
      Object ETag.
    </ResponseField>

    <ResponseField name="files[].metadata" type="object">
      Only present when `include_metadata=true` and a sidecar metadata file
      exists. Contains `description`, `summary`, and `keywords`.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  curl -X GET \
    "https://bouncer.nunu.ai/file-storage/my-project/project?include_metadata=true" \
    -H "X-Api-Key: YOUR_API_TOKEN"
  ```

  ```typescript JavaScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  const projectId = "my-project";

  const response = await fetch(
    `https://bouncer.nunu.ai/file-storage/${projectId}/project?include_metadata=true`,
    {
      headers: {
        "X-Api-Key": process.env.NUNU_API_TOKEN,
      },
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import requests
  import os

  project_id = "my-project"

  response = requests.get(
      f"https://bouncer.nunu.ai/file-storage/{project_id}/project",
      headers={"X-Api-Key": os.environ["NUNU_API_TOKEN"]},
      params={"include_metadata": True},
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  {
    "projectId": "my-project",
    "scope": "project",
    "count": 2,
    "files": [
      {
        "filename": "game-design.md",
        "path": "game-design.md",
        "size": 4096,
        "uploaded": "2026-04-12T10:30:00.000Z",
        "etag": "9a3b4c5d6e7f8090a1b2c3d4e5f60718",
        "metadata": {
          "description": "High-level design overview",
          "summary": "Mechanics, levels, and progression",
          "keywords": ["design", "gameplay"]
        }
      },
      {
        "filename": "rules.txt",
        "path": "subdir/rules.txt",
        "size": 1234,
        "uploaded": "2026-04-12T10:31:00.000Z",
        "etag": "0a1b2c3d4e5f60718a3b4c5d6e7f8090"
      }
    ]
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /file-storage/{projectId}/project
openapi: 3.1.0
info:
  title: nunu.ai API
  description: >-
    The nunu.ai Public API allows you to programmatically interact with your
    projects, manage test runs, and upload builds.
  version: 1.0.0
servers:
  - url: https://nunu.ai/api/v1
security:
  - apiKeyAuth: []
paths:
  /file-storage/{projectId}/project:
    servers:
      - url: https://bouncer.nunu.ai
        description: Bouncer service (artifact and knowledge delivery)
    get:
      tags:
        - Knowledge
      summary: List Project-Scope Knowledge
      description: >-
        List the knowledge files stored under the project's project/ prefix
        only. These files are visible to every run in the project.
      operationId: listProjectKnowledgeFiles
      parameters:
        - name: projectId
          in: path
          required: true
          description: >-
            The nunu.ai project ID. Must match the project the API key is scoped
            to.
          schema:
            type: string
        - name: include_metadata
          in: query
          required: false
          description: >-
            When true, attach parsed metadata (description, summary, keywords)
            for each file from its .{name}.meta.json sidecar.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProjectKnowledgeFilesResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - API key does not match the requested project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ListProjectKnowledgeFilesResponse:
      type: object
      required:
        - projectId
        - scope
        - count
        - files
      properties:
        projectId:
          type: string
        scope:
          type: string
          enum:
            - project
        count:
          type: integer
        files:
          type: array
          items:
            $ref: '#/components/schemas/KnowledgeFile'
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        details:
          type: object
    KnowledgeFile:
      type: object
      required:
        - filename
        - path
        - size
        - uploaded
        - etag
      properties:
        filename:
          type: string
          description: Basename of the file (no directory prefix).
        path:
          type: string
          description: >-
            Path of the file relative to the scope root (may include
            subdirectories).
        size:
          type: integer
          description: File size in bytes.
        uploaded:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the file was last written.
        etag:
          type: string
          description: Object ETag.
        metadata:
          $ref: '#/components/schemas/KnowledgeFileMetadata'
          description: >-
            Only present when include_metadata=true and a sidecar metadata file
            exists.
    KnowledgeFileMetadata:
      type: object
      description: Parsed metadata from the .{filename}.meta.json sidecar.
      properties:
        description:
          type: string
          description: Free-form description of the file.
        summary:
          type: string
          description: Short summary used by agents to decide whether to read the file.
        keywords:
          type: array
          items:
            type: string
          description: Searchable keywords associated with the file.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key for authentication

````