diff --git a/docs/bruno/README.md b/docs/bruno/README.md
new file mode 100644
index 0000000..f194a3b
--- /dev/null
+++ b/docs/bruno/README.md
@@ -0,0 +1,29 @@
+# Agents API - Bruno Collection
+
+Minimal Bruno API test collection for agent endpoints.
+
+## Setup
+
+1. Install Bruno: https://www.usebruno.com/
+2. Open this collection in Bruno
+3. Configure environment variables:
+   - `baseUrl`: Your API base URL (e.g., `http://localhost:3000`)
+
+## Endpoints
+
+### Public Endpoints
+- `GET /api/agents` - List agents
+- `GET /api/agents/:owner/:name` - Get agent details
+- `GET /api/agents/:owner/:name/versions` - List agent versions
+
+### Protected Endpoints (require authentication)
+- `POST /api/agents` - Publish agent
+- `PATCH /api/agents/:owner/:name` - Update agent metadata
+- `DELETE /api/agents/:owner/:name` - Delete agent
+
+## Usage
+
+1. Start with public endpoints to verify API is working
+2. Authenticate via your auth flow
+3. Test protected endpoints with auth token
+4. Update request bodies/params as needed for your test data
diff --git a/docs/bruno/agents/delete-agent.bru b/docs/bruno/agents/delete-agent.bru
new file mode 100644
index 0000000..adc81f2
--- /dev/null
+++ b/docs/bruno/agents/delete-agent.bru
@@ -0,0 +1,34 @@
+meta {
+  name: DELETE /api/agents/:owner/:name
+  type: http
+  seq: 5
+}
+
+delete {
+  url: {{baseUrl}}/api/agents/testuser/my-agent
+  body: none
+  auth: inherit
+}
+
+tests {
+  test("should return 200 status", () => {
+    expect(res.getStatus()).to.equal(200);
+  });
+  
+  test("should confirm deletion", () => {
+    expect(res.getBody()).to.have.property('success', true);
+    expect(res.getBody()).to.have.property('message');
+  });
+}
+
+docs {
+  Delete an agent and all its versions.
+  Requires authentication and ownership.
+  
+  Path Parameters:
+  - owner: Username of the agent owner
+  - name: Agent name
+  
+  Query Parameters (optional):
+  - version: Delete specific version instead of entire agent
+}
diff --git a/docs/bruno/agents/get-agent.bru b/docs/bruno/agents/get-agent.bru
new file mode 100644
index 0000000..81c0d48
--- /dev/null
+++ b/docs/bruno/agents/get-agent.bru
@@ -0,0 +1,37 @@
+meta {
+  name: GET /api/agents/:owner/:name
+  type: http
+  seq: 2
+}
+
+get {
+  url: {{baseUrl}}/api/agents/testuser/my-agent
+  body: none
+  auth: inherit
+}
+
+tests {
+  test("should return 200 status", () => {
+    expect(res.getStatus()).to.equal(200);
+  });
+  
+  test("should return agent detail", () => {
+    expect(res.getBody()).to.have.property('success', true);
+    expect(res.getBody()).to.have.property('data');
+    
+    const agent = res.getBody().data;
+    expect(agent).to.have.property('name');
+    expect(agent).to.have.property('owner');
+    expect(agent).to.have.property('latestVersion');
+    expect(agent).to.have.property('content');
+    expect(agent).to.have.property('stats');
+  });
+}
+
+docs {
+  Get agent details including latest version content.
+  
+  Path Parameters:
+  - owner: Username of the agent owner
+  - name: Agent name (lowercase alphanumeric with hyphens)
+}
diff --git a/docs/bruno/agents/get-versions.bru b/docs/bruno/agents/get-versions.bru
new file mode 100644
index 0000000..f2d8473
--- /dev/null
+++ b/docs/bruno/agents/get-versions.bru
@@ -0,0 +1,43 @@
+meta {
+  name: GET /api/agents/:owner/:name/versions
+  type: http
+  seq: 4
+}
+
+get {
+  url: {{baseUrl}}/api/agents/testuser/my-agent/versions
+  body: none
+  auth: inherit
+}
+
+tests {
+  test("should return 200 status", () => {
+    expect(res.getStatus()).to.equal(200);
+  });
+  
+  test("should return versions list", () => {
+    expect(res.getBody()).to.have.property('name');
+    expect(res.getBody()).to.have.property('owner');
+    expect(res.getBody()).to.have.property('versions');
+    expect(res.getBody().versions).to.be.an('array');
+  });
+  
+  test("should have version details", () => {
+    const body = res.getBody();
+    if (body.versions.length > 0) {
+      const version = body.versions[0];
+      expect(version).to.have.property('version');
+      expect(version).to.have.property('publishedAt');
+      expect(version).to.have.property('downloads');
+      expect(version).to.have.property('isLatest');
+    }
+  });
+}
+
+docs {
+  List all versions of an agent.
+  
+  Path Parameters:
+  - owner: Username of the agent owner
+  - name: Agent name
+}
diff --git a/docs/bruno/agents/list-agents.bru b/docs/bruno/agents/list-agents.bru
new file mode 100644
index 0000000..93cb4d0
--- /dev/null
+++ b/docs/bruno/agents/list-agents.bru
@@ -0,0 +1,56 @@
+meta {
+  name: GET /api/agents
+  type: http
+  seq: 1
+}
+
+get {
+  url: {{baseUrl}}/api/agents?page=1&limit=20
+  body: none
+  auth: inherit
+}
+
+params:query {
+  page: 1
+  limit: 20
+  ~visibility: public
+  ~sort: downloads
+}
+
+tests {
+  test("should return 200 status", () => {
+    expect(res.getStatus()).to.equal(200);
+  });
+  
+  test("should return agents list with pagination", () => {
+    expect(res.getBody()).to.have.property('agents');
+    expect(res.getBody().agents).to.be.an('array');
+    expect(res.getBody()).to.have.property('pagination');
+    expect(res.getBody().pagination).to.have.property('page');
+    expect(res.getBody().pagination).to.have.property('total');
+  });
+  
+  test("should return agents in UI format", () => {
+    const body = res.getBody();
+    if (body.agents.length > 0) {
+      const agent = body.agents[0];
+      expect(agent).to.have.property('name');
+      expect(agent).to.have.property('owner');
+      expect(agent).to.have.property('latestVersion');
+      expect(agent).to.have.property('downloads');
+      expect(agent).to.have.property('visibility');
+    }
+  });
+}
+
+docs {
+  List agents with pagination and filtering.
+  
+  Query Parameters:
+  - page: Page number (default: 1)
+  - limit: Items per page (1-100, default: 20)
+  - visibility: Filter by visibility (public/private/all)
+  - sort: Sort by (downloads/updated/created/name)
+  - owner: Filter by owner username
+  - tag: Filter by tag
+}
diff --git a/docs/bruno/agents/publish-agent.bru b/docs/bruno/agents/publish-agent.bru
new file mode 100644
index 0000000..2a576dd
--- /dev/null
+++ b/docs/bruno/agents/publish-agent.bru
@@ -0,0 +1,55 @@
+meta {
+  name: POST /api/agents
+  type: http
+  seq: 3
+}
+
+post {
+  url: {{baseUrl}}/api/agents
+  body: json
+  auth: inherit
+}
+
+body:json {
+  {
+    "name": "test-agent",
+    "description": "A test agent for demonstration",
+    "visibility": "public",
+    "version": "1.0.0",
+    "content": "export default function agent() { return 'Hello World'; }",
+    "tags": ["test", "demo"],
+    "changelog": "Initial release"
+  }
+}
+
+tests {
+  test("should return 201 status", () => {
+    expect(res.getStatus()).to.equal(201);
+  });
+  
+  test("should return published agent info", () => {
+    expect(res.getBody()).to.have.property('success', true);
+    expect(res.getBody()).to.have.property('agent');
+    
+    const agent = res.getBody().agent;
+    expect(agent).to.have.property('name');
+    expect(agent).to.have.property('owner');
+    expect(agent).to.have.property('version');
+    expect(agent).to.have.property('publishedAt');
+  });
+}
+
+docs {
+  Publish a new agent or new version of an existing agent.
+  Requires authentication.
+  
+  Body:
+  - name: Agent name (3-50 chars, lowercase alphanumeric with hyphens)
+  - description: Description (10-500 chars, optional)
+  - visibility: "public" or "private"
+  - version: Semantic version (e.g., "1.0.0")
+  - content: Agent code (max 100KB)
+  - tags: Array of tags (max 10, optional)
+  - changelog: Version changelog (max 1000 chars, optional)
+  - readme: README content (max 50KB, optional)
+}
diff --git a/docs/bruno/bruno.json b/docs/bruno/bruno.json
new file mode 100644
index 0000000..02bd3a5
--- /dev/null
+++ b/docs/bruno/bruno.json
@@ -0,0 +1,6 @@
+{
+  "version": "1",
+  "name": "Agents API",
+  "type": "collection",
+  "ignore": ["node_modules", ".git"]
+}
diff --git a/docs/bruno/environments/development.bru b/docs/bruno/environments/development.bru
new file mode 100644
index 0000000..eb3aa4d
--- /dev/null
+++ b/docs/bruno/environments/development.bru
@@ -0,0 +1,3 @@
+vars {
+  baseUrl: https://dev.agentage.io/
+}
diff --git a/docs/bruno/environments/localhost.bru b/docs/bruno/environments/localhost.bru
new file mode 100644
index 0000000..739f95b
--- /dev/null
+++ b/docs/bruno/environments/localhost.bru
@@ -0,0 +1,3 @@
+vars {
+  baseUrl: localhost:3000
+}