Skip to main content
GET
/
file-storage
/
{projectId}
curl -X GET \
  "https://bouncer.nunu.ai/file-storage/my-project?include_metadata=true" \
  -H "X-Api-Key: YOUR_API_TOKEN"

{
  "projectId": "my-project",
  "count": 3,
  "sections": [
    {
      "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"
        }
      ]
    },
    {
      "scope": "agent",
      "id": "a1b2c3",
      "count": 1,
      "files": [
        {
          "filename": "agent-prompt.md",
          "path": "agent-prompt.md",
          "size": 512,
          "uploaded": "2026-04-12T10:35:00.000Z",
          "etag": "1b2c3d4e5f60718a3b4c5d6e7f80909a"
        }
      ]
    },
    {
      "scope": "test_case",
      "id": "t1t2t3",
      "count": 0,
      "files": []
    }
  ]
}

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.

Permission Required: any API key scoped to the requested project
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.
Knowledge files are user-uploaded reference material (design docs, specs, guides, etc.) that nunu agents can read while running. Files are organized by scope:
ScopePath on storageVisible to
project{projectId}/project/Every run in the project
agent{projectId}/agent/{agentId}/Runs that use the given agent
test_case{projectId}/test_case/{testCaseId}/Runs that execute the given test
This endpoint always returns project-scope files, and optionally appends agent- and/or test-case-scope files when their IDs are passed as query parameters.

​
Path Parameters

​
projectId
string
required
The nunu.ai project ID. Must match the project the API key is scoped to.

​
Query Parameters

​
agent_id
string
Include files from agent/{agent_id}/ in the response.
​
test_case_id
string
Include files from test_case/{test_case_id}/ in the response.
​
include_metadata
boolean
default:"false"
When true, attach the parsed metadata (description, summary, keywords) for each file. Metadata is stored alongside each file as a hidden .{name}.meta.json sidecar.

​
Response

​
projectId
string
required
Echo of the path parameter.
​
count
integer
required
Total number of files across all included sections.
​
sections
Section[]
required
One section per scope returned. The project section is always present; other sections are only present when the corresponding query parameter is set.

​
File Object

​
filename
string
required
Basename of the file (no directory prefix).
​
path
string
required
Path of the file relative to the scope root (may include subdirectories).
​
size
integer
required
File size in bytes.
​
uploaded
string
required
ISO 8601 timestamp when the file was last written.
​
etag
string
required
Object ETag.
​
metadata
object
Only present when include_metadata=true and a sidecar metadata file exists.
curl -X GET \
  "https://bouncer.nunu.ai/file-storage/my-project?include_metadata=true" \
  -H "X-Api-Key: YOUR_API_TOKEN"

{
  "projectId": "my-project",
  "count": 3,
  "sections": [
    {
      "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"
        }
      ]
    },
    {
      "scope": "agent",
      "id": "a1b2c3",
      "count": 1,
      "files": [
        {
          "filename": "agent-prompt.md",
          "path": "agent-prompt.md",
          "size": 512,
          "uploaded": "2026-04-12T10:35:00.000Z",
          "etag": "1b2c3d4e5f60718a3b4c5d6e7f80909a"
        }
      ]
    },
    {
      "scope": "test_case",
      "id": "t1t2t3",
      "count": 0,
      "files": []
    }
  ]
}

Authorizations

​
X-Api-Key
string
header
required

API key for authentication

Path Parameters

​
projectId
string
required

The nunu.ai project ID. Must match the project the API key is scoped to.

Query Parameters

​
agent_id
string

Include files from agent/{agent_id}/ in the response.

​
test_case_id
string

Include files from test_case/{test_case_id}/ in the response.

​
include_metadata
boolean
default:false

When true, attach parsed metadata (description, summary, keywords) for each file from its .{name}.meta.json sidecar.

Response

Successful response

​
projectId
string
required

Echo of the path parameter.

​
count
integer
required

Total number of files across all included sections.

​
sections
object[]
required

One section per scope returned. The project section is always present; other sections only appear when their query param is set.