> ## 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 Agent-Scope Knowledge
> List the knowledge files attached to a specific agent configuration in the given project.
**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.
Returns the files stored under `agent/{agentId}/` for the given project. These
are reference files that nunu attaches to runs that use a specific agent
configuration.
To get project-, agent-, and test-case-scope files in a single call, use
[List Knowledge Files](/api-reference/knowledge/list-files) instead.
## Path Parameters
The nunu.ai project ID. Must match the project the API key is scoped to.
The agent ID whose files you want to list.
## Query Parameters
When `true`, attach parsed metadata (`description`, `summary`, `keywords`)
for each file from its `.{name}.meta.json` sidecar.
## Response
Echo of the path parameter.
Always `"agent"` for this endpoint.
Echo of the path parameter.
Number of files returned.
Files in the agent scope. See
[List Knowledge Files](/api-reference/knowledge/list-files#file-object) for
the full file shape.
```bash cURL theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
curl -X GET \
"https://bouncer.nunu.ai/file-storage/my-project/agent/a1b2c3?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 agentId = "a1b2c3";
const response = await fetch(
`https://bouncer.nunu.ai/file-storage/${projectId}/agent/${agentId}?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"
agent_id = "a1b2c3"
response = requests.get(
f"https://bouncer.nunu.ai/file-storage/{project_id}/agent/{agent_id}",
headers={"X-Api-Key": os.environ["NUNU_API_TOKEN"]},
params={"include_metadata": True},
)
data = response.json()
```
```json 200 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
"projectId": "my-project",
"scope": "agent",
"agentId": "a1b2c3",
"count": 1,
"files": [
{
"filename": "agent-prompt.md",
"path": "agent-prompt.md",
"size": 512,
"uploaded": "2026-04-12T10:35:00.000Z",
"etag": "1b2c3d4e5f60718a3b4c5d6e7f80909a",
"metadata": {
"description": "System prompt for this agent",
"summary": "Routing rules and persona",
"keywords": ["prompt", "agent"]
}
}
]
}
```
## OpenAPI
````yaml GET /file-storage/{projectId}/agent/{agentId}
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}/agent/{agentId}:
servers:
- url: https://bouncer.nunu.ai
description: Bouncer service (artifact and knowledge delivery)
get:
tags:
- Knowledge
summary: List Agent-Scope Knowledge
description: >-
List the knowledge files attached to a specific agent configuration in
the given project.
operationId: listAgentKnowledgeFiles
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: agentId
in: path
required: true
description: The agent ID whose files you want to list.
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/ListAgentKnowledgeFilesResponse'
'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:
ListAgentKnowledgeFilesResponse:
type: object
required:
- projectId
- scope
- agentId
- count
- files
properties:
projectId:
type: string
scope:
type: string
enum:
- agent
agentId:
type: string
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
````