Skip to content

docs: add agent templates section and endpoint for listing templates #197

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ahmednahima0-beep wants to merge 8 commits into from
+140 −1
Closed

docs: add agent templates section and endpoint for listing templates #197

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
91a7e54
docs: add agent templates section and endpoint for listing templates
ahmednahima0-beep May 9, 2026
85d166f
docs(openapi): update agent templates endpoint and security specifica…
ahmednahima0-beep May 9, 2026
1a77ec5
docs(openapi): simplify agent templates endpoint reference
ahmednahima0-beep May 9, 2026
5ec5afd
docs(openapi): clarify agent templates endpoint description
ahmednahima0-beep May 9, 2026
aaf62f9
docs(openapi): update agent templates schema to include 'is_favourite'
ahmednahima0-beep May 9, 2026
ae3ac5e
docs(openapi): refine agent templates endpoint descriptions
ahmednahima0-beep May 9, 2026
4b1060c
docs: update navigation and endpoint references for agent templates
ahmednahima0-beep May 12, 2026
9bb9098
docs(openapi): refine agent templates endpoint description
ahmednahima0-beep May 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions api-reference/agent-templates/list.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: List Agent Templates
openapi: '/api-reference/openapi/agent-templates.json GET /api/agents/templates'
---
Comment thread
coderabbitai[bot] marked this conversation as resolved.
129 changes: 129 additions & 0 deletions api-reference/openapi/agent-templates.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
{
"openapi": "3.1.0",
"info": {
"title": "Recoup API - Agent Templates",
"description": "Lists agent prompt templates (`GET /api/agents/templates`). Clients use the Recoup API base URL from `servers`.",
"license": {
"name": "MIT"
},
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.recoupable.com"
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Use the chat server here (or add an operation-level override); this endpoint is documented on https://chat.recoupable.com elsewhere, so the new spec points readers at the wrong host.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/agent-templates.json, line 13:

<comment>Use the chat server here (or add an operation-level override); this endpoint is documented on `https://chat.recoupable.com` elsewhere, so the new spec points readers at the wrong host.</comment>

<file context>
@@ -0,0 +1,102 @@
+  },
+  "servers": [
+    {
+      "url": "https://api.recoupable.com"
+    }
+  ],
</file context>

Copy link
Copy Markdown
Collaborator Author

@ahmednahima0-beep ahmednahima0-beep May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

already implemented

Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update—glad it’s already addressed.

}
Comment on lines +11 to +14
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 9, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Align the server host with the other spec for this endpoint.

This standalone spec uses api.recoupable.com, but api-reference/openapi/research.json documents the same GET /api/agent-templates operation on chat.recoupable.com. Since api-reference/agent-templates/list.mdx points at this file, the rendered examples and “Try it” target will be wrong unless both specs agree.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@api-reference/openapi/agent-templates.json` around lines 11 - 14, Update the
OpenAPI servers URL in this spec so it matches the other spec: replace the
"servers" -> "url" value "https://api.recoupable.com" with
"https://chat.recoupable.com" to ensure the documented GET /api/agent-templates
endpoint and the examples/“Try it” target align with the research.json spec;
verify the servers.url string exactly matches the other spec.

Copy link
Copy Markdown
Collaborator Author

@ahmednahima0-beep ahmednahima0-beep May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

already implemented

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check the current server URL in agent-templates.json
rg -n "url" api-reference/openapi/agent-templates.json

Length of output: 45

@ahmednahima0-beep, the fix doesn't appear to be in the branch yet — api-reference/openapi/agent-templates.json line 13 still reads:

"url": "https://api.recoupable.com"

It needs to be updated to match research.json:

"url": "https://chat.recoupable.com"

Could you double-check that the commit was pushed to the docs/agent-templates-get-endpoint branch?

],
"paths": {
"/api/agents/templates": {
"get": {
"description": "Returns agent prompt templates visible to the **authenticated** caller. The account is resolved from `Authorization: Bearer` or `x-api-key`. Response includes public templates, templates the caller owns, and private templates shared with the caller. Each row includes `is_favourite` for that caller. For **private templates the caller owns**, `shared_emails` lists recipients the template was shared with; for others it is empty.",
"parameters": [],
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Templates retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentTemplate"
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: Broken $ref references: #/components/schemas/AgentTemplate and #/components/schemas/AgentTemplatesErrorResponse are referenced in this operation but neither schema is defined in research.json's components section. The spec will fail validation and documentation rendering will be broken for this endpoint.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/agent-templates.json, line 39:

<comment>Broken `$ref` references: `#/components/schemas/AgentTemplate` and `#/components/schemas/AgentTemplatesErrorResponse` are referenced in this operation but neither schema is defined in `research.json`'s `components` section. The spec will fail validation and documentation rendering will be broken for this endpoint.</comment>

<file context>
@@ -0,0 +1,102 @@
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/AgentTemplate"
+                  }
+                }
</file context>

Copy link
Copy Markdown
Collaborator Author

@ahmednahima0-beep ahmednahima0-beep May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

already implemented

Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update—glad it’s implemented!

}
}
}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentTemplatesError"
}
}
}
},
"500": {
"description": "Failed to fetch templates",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentTemplatesError"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
},
"apiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "x-api-key",
"description": "Your Recoup API key. [Learn more](/quickstart#api-keys)."
}
},
"schemas": {
"AgentTemplate": {
"type": "object",
"description": "A stored agent template row as returned from the API.",
"required": [
"id",
"title",
"description",
"prompt",
"is_private",
"is_favourite"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"title": { "type": "string" },
"description": { "type": "string" },
"prompt": { "type": "string" },
"tags": {
"type": "array",
"items": { "type": "string" },
"nullable": true
},
"creator": { "type": "string", "nullable": true },
"is_private": { "type": "boolean" },
"created_at": { "type": "string", "nullable": true },
"favorites_count": { "type": "integer", "nullable": true },
"updated_at": { "type": "string", "nullable": true },
"is_favourite": {
"type": "boolean",
"description": "Whether this template is a favorite for the authenticated caller."
},
"shared_emails": {
"type": "array",
"items": { "type": "string", "format": "email" },
"description": "Email addresses for accounts the template is shared with — only populated for **private templates owned by** the authenticated caller; otherwise empty array."
}
}
},
"AgentTemplatesError": {
"type": "object",
"properties": {
"error": { "type": "string" }
}
}
}
}
}
8 changes: 7 additions & 1 deletion docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,12 +229,18 @@
"tab": "Agents & Sandboxes",
"groups": [
{
"group": "Agent Onboarding",
"group": "Workflows",
Copy link
Copy Markdown
Collaborator

@sweetmantech sweetmantech May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why are you changing this header?

"pages": [
"api-reference/agents/signup",
"api-reference/agents/verify"
]
},
{
"group": "Templates",
"pages": [
"api-reference/agent-templates/list"
]
},
{
"group": "Agents",
"pages": [
Expand Down