docs: add agent templates section and endpoint for listing templates#197
docs: add agent templates section and endpoint for listing templates#197ahmednahima0-beep wants to merge 8 commits into
Conversation
- Introduced a new section in the documentation for "Agent templates" with a reference to the new endpoint for listing agent templates. - Added the OpenAPI specification for the `/api/agent-templates` endpoint, detailing the GET method, parameters, and response schemas for retrieving saved prompt templates. - Updated the navigation structure in `docs.json` to include the new agent templates group.
📝 WalkthroughWalkthroughAdds an OpenAPI 3.1 spec and MDX page for GET /api/agents/templates, including AgentTemplate and AgentTemplatesError schemas, apiKey/bearer security schemes, and a navigation entry under Agents & Sandboxes. ChangesAgent Templates API Documentation
Sequence Diagram(s)sequenceDiagram
participant Client
participant Endpoint as GET /api/agents/templates
participant Response
Client->>Endpoint: Authorization: Bearer / x-api-key
alt Authenticated
Endpoint->>Response: 200 OK (AgentTemplate[])
Response-->>Client: AgentTemplate[]
else Unauthorized
Endpoint->>Response: 401 Unauthorized (AgentTemplatesError)
Response-->>Client: AgentTemplatesError
else Server Error
Endpoint->>Response: 500 Internal Server Error (AgentTemplatesError)
Response-->>Client: AgentTemplatesError
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with 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.
Inline comments:
In `@api-reference/agent-templates/list.mdx`:
- Around line 1-4: The frontmatter `openapi` value contains the OpenAPI spec
path plus method/path; update it to the required "METHOD /path" form by
replacing the current value '/api-reference/openapi/agent-templates.json GET
/api/agent-templates' with "GET /api/agent-templates" in the frontmatter (the
lines with `openapi:` at the top of the file) so it matches the coding guideline
for api-reference/*.mdx pages.
In `@api-reference/openapi/agent-templates.json`:
- Around line 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.
- Around line 17-55: The GET operation for "/api/agent-templates" lacks security
metadata and missing 401/403 responses for user-scoped access; update the
operation object for "get" to include a proper security requirement (e.g., the
existing bearerAuth or ApiKeyAuth scheme used by the API) and add standardized
401 (Unauthorized) and 403 (Forbidden) response entries referencing or creating
error schemas (e.g., AgentTemplatesError) that explain
authentication/authorization failures and that sensitive fields like
shared_emails are only returned when authenticated and authorized for the
provided userId. Ensure the security requirement and response objects are added
to the same "get" operation block so consumers and codegen see auth enforced.
In `@api-reference/openapi/research.json`:
- Around line 295-315: The OpenAPI operation references missing schemas
AgentTemplate and AgentTemplatesErrorResponse; update the document so the $ref
targets are valid or add these schemas to components. Either add definitions
named AgentTemplate and AgentTemplatesErrorResponse under the document's
components.schemas in research.json, or change the two $ref values in this
operation to point to the existing schema names (e.g., the correct
components/schemas/* entries used elsewhere). Ensure the names exactly match the
component keys (AgentTemplate, AgentTemplatesErrorResponse) and that both the
200 response items and 500 response schema reference the corrected component
paths.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 9cf1253a-925b-4ab9-83bf-e11626a1240b
📒 Files selected for processing (4)
api-reference/agent-templates/list.mdxapi-reference/openapi/agent-templates.jsonapi-reference/openapi/research.jsondocs.json
| "servers": [ | ||
| { | ||
| "url": "https://api.recoupable.com" | ||
| } |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
already implemented
There was a problem hiding this comment.
🧩 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?
There was a problem hiding this comment.
3 issues found across 4 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="api-reference/openapi/research.json">
<violation number="1" location="api-reference/openapi/research.json:303">
P1: These response refs don't exist in this OpenAPI file, so the new endpoint can't resolve its 200/500 schemas.</violation>
</file>
<file name="api-reference/openapi/agent-templates.json">
<violation number="1" location="api-reference/openapi/agent-templates.json:13">
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.</violation>
<violation number="2" location="api-reference/openapi/agent-templates.json:39">
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.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
| "schema": { | ||
| "type": "array", | ||
| "items": { | ||
| "$ref": "#/components/schemas/AgentTemplate" |
There was a problem hiding this comment.
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>
There was a problem hiding this comment.
already implemented
There was a problem hiding this comment.
Thanks for the update—glad it’s implemented!
| }, | ||
| "servers": [ | ||
| { | ||
| "url": "https://api.recoupable.com" |
There was a problem hiding this comment.
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>
There was a problem hiding this comment.
already implemented
There was a problem hiding this comment.
Thanks for the update—glad it’s already addressed.
…tions - Revised the description for the `/api/agent-templates` GET endpoint to clarify that it returns templates visible to the authenticated caller, removing the `userId` parameter. - Updated security requirements to include both `bearerAuth` and `apiKeyAuth` schemes. - Added a new response for 401 errors to handle missing or invalid credentials. - Enhanced the `AgentTemplate` schema descriptions for clarity regarding favorite templates and shared emails.
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="api-reference/openapi/agent-templates.json">
<violation number="1" location="api-reference/openapi/agent-templates.json:19">
P2: Keep the `is_favourite` guarantee consistent with the schema. Right now the description says every row includes it, but the schema still treats it as optional.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
- Updated the OpenAPI documentation for the `/api/agent-templates` endpoint by removing the server URL and unnecessary details, streamlining the reference to just the GET method. - This change enhances clarity and focuses on the essential information for users accessing the agent templates.
- Updated the description for the `/api/agent-templates` endpoint to specify that it lists agent prompt templates and is documented solely in this section, enhancing clarity for users accessing the API.
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="api-reference/openapi/agent-templates.json">
<violation number="1" location="api-reference/openapi/agent-templates.json:5">
P3: Custom agent: **Flag AI Slop and Fabricated Changes**
The description makes an absolute claim that this endpoint is documented only here, but the repo already documents `GET /api/agent-templates` in another docs page.</violation>
</file>
Tip: Review your code locally with the cubic CLI to iterate faster.
- Added 'is_favourite' to the required properties of the AgentTemplate schema in the OpenAPI documentation for the `/api/agent-templates` endpoint, ensuring that users are aware of this new field's necessity when interacting with the API.
- Enhanced the descriptions for the `/api/agent-templates` endpoint to clarify the conditions under which `shared_emails` are populated, specifying that it only applies to private templates owned by the authenticated caller. This improves user understanding of the API's behavior regarding shared templates.
There was a problem hiding this comment.
🧹 Nitpick comments (1)
api-reference/openapi/agent-templates.json (1)
34-39: ⚡ Quick winAdd
maxItemsconstraints to array schemas.The response array and nested array properties (
tags,shared_emails) lackmaxItemsconstraints, which can lead to performance issues and potential abuse through oversized payloads. Consider adding reasonable limits:
- Response array (line 35): Set a maximum page size (e.g., 100 or 1000 templates)
tagsarray (line 101): Limit to a reasonable number (e.g., 20 tags)shared_emailsarray (line 115): Limit sharing scope (e.g., 50 recipients)🔒 Suggested constraints
"schema": { "type": "array", + "maxItems": 1000, "items": { "$ref": "#/components/schemas/AgentTemplate""tags": { "type": "array", + "maxItems": 20, "items": { "type": "string" },"shared_emails": { "type": "array", + "maxItems": 50, "items": { "type": "string", "format": "email" },🤖 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 34 - 39, The array schemas need maxItems limits: add a "maxItems" (e.g., 100 or 1000) to the top-level response array schema that references AgentTemplate, and add "maxItems": 20 to the AgentTemplate.tags property and "maxItems": 50 to the AgentTemplate.shared_emails property; update the JSON schema entries that contain the "$ref": "#/components/schemas/AgentTemplate" for the response array and the "tags" and "shared_emails" properties inside the AgentTemplate schema to include these maxItems constraints.
🤖 Prompt for all review comments with 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.
Nitpick comments:
In `@api-reference/openapi/agent-templates.json`:
- Around line 34-39: The array schemas need maxItems limits: add a "maxItems"
(e.g., 100 or 1000) to the top-level response array schema that references
AgentTemplate, and add "maxItems": 20 to the AgentTemplate.tags property and
"maxItems": 50 to the AgentTemplate.shared_emails property; update the JSON
schema entries that contain the "$ref": "#/components/schemas/AgentTemplate" for
the response array and the "tags" and "shared_emails" properties inside the
AgentTemplate schema to include these maxItems constraints.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 4ef18e42-c772-4894-a164-84088497a4c7
📒 Files selected for processing (2)
api-reference/agent-templates/list.mdxapi-reference/openapi/agent-templates.json
✅ Files skipped from review due to trivial changes (1)
- api-reference/agent-templates/list.mdx
| "paths": { | ||
| "/api/agent-templates": { | ||
| "get": { | ||
| "description": "Returns agent prompt templates visible to the **authenticated** caller. The account is resolved from `Authorization: Bearer` or `x-api-key` — there is no `userId` query parameter; clients cannot request another principal's scope. 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 other rows it is empty.", |
There was a problem hiding this comment.
KISS principle.
| "description": "Returns agent prompt templates visible to the **authenticated** caller. The account is resolved from `Authorization: Bearer` or `x-api-key` — there is no `userId` query parameter; clients cannot request another principal's scope. 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 other rows it is empty.", | |
| "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.", |
There was a problem hiding this comment.
I updated correctly
- Changed the group name from "Agent Onboarding" to "Workflows" in `docs.json` for better categorization. - Updated the group name from "Agent templates" to "Templates" to align with naming conventions. - Revised the OpenAPI reference in `list.mdx` to reflect the new endpoint path `/api/agents/templates` instead of `/api/agent-templates`. - Adjusted the description in `agent-templates.json` to match the updated endpoint path, ensuring consistency across documentation.
There was a problem hiding this comment.
🧹 Nitpick comments (4)
api-reference/openapi/agent-templates.json (4)
121-126: ⚡ Quick winMark
erroras required in the error schema.The
AgentTemplatesErrorschema should markerroras required so API consumers and code generators can rely on its presence in 401 and 500 responses.🛡️ Make error field required
"AgentTemplatesError": { "type": "object", + "required": ["error"], "properties": { "error": { "type": "string" } } }🤖 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 121 - 126, The AgentTemplatesError schema currently defines an "error" property but doesn't guarantee its presence; update the "AgentTemplatesError" schema to include a required array with "error" (i.e., add "required": ["error"]) so API consumers and code generators can rely on the field being present in 401/500 responses.
107-109: ⚡ Quick winAdd
format: "date-time"to timestamp fields.The
created_atandupdated_atfields are documented as strings but likely represent ISO 8601 timestamps. Addingformat: "date-time"improves validation and code generation.📅 Add format hints for timestamps
- "created_at": { "type": ["string", "null"] }, + "created_at": { "type": ["string", "null"], "format": "date-time" }, "favorites_count": { "type": ["integer", "null"] }, - "updated_at": { "type": ["string", "null"] }, + "updated_at": { "type": ["string", "null"], "format": "date-time" },Note: Apply this after the nullable refactor from the previous comment.
🤖 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 107 - 109, The OpenAPI schema fields created_at and updated_at are defined as nullable strings but should include format: "date-time"; update the agent-templates.json entries for "created_at" and "updated_at" (keeping nullable: true per the nullable refactor) to add format: "date-time" so validators and generators treat them as ISO 8601 timestamps.
17-42: ⚡ Quick winConsider documenting pagination for the templates list.
The endpoint returns an unbounded array of templates with no
limit,offset, or cursor parameters documented. If users can create or access many templates, responses may grow large and slow. Consider adding pagination parameters and response metadata (e.g.,total_count,next_page) or documenting the expected max template count if pagination is deferred.🤖 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 17 - 42, The OpenAPI spec for the /api/agents/templates GET currently returns an unbounded array of AgentTemplate; add pagination by introducing query parameters (e.g., limit: integer, offset: integer OR cursor: string) in the "parameters" array for that operation and replace the response schema with a paginated wrapper (e.g., PaginatedAgentTemplateList) that includes items: array of AgentTemplate, plus metadata fields like total_count, next_cursor/next_page (and optionally page, per_page) so clients can page results; update components/schemas to define the new paginated schema and ensure the operation's description mentions default/maximum limits and behavior when using cursor vs offset.
100-109: ⚡ Quick winReplace deprecated
nullable: truewith OpenAPI 3.1 type arrays.OpenAPI 3.1 replaced the
nullablekeyword with union types. Lines 103, 105, 107, 108, and 109 usenullable: true, which is deprecated.♻️ Modernize nullable fields for OpenAPI 3.1
"tags": { - "type": "array", - "items": { "type": "string" }, - "nullable": true + "type": ["array", "null"], + "items": { "type": "string" } }, - "creator": { "type": "string", "nullable": true }, + "creator": { "type": ["string", "null"] }, "is_private": { "type": "boolean" }, - "created_at": { "type": "string", "nullable": true }, - "favorites_count": { "type": "integer", "nullable": true }, - "updated_at": { "type": "string", "nullable": true }, + "created_at": { "type": ["string", "null"] }, + "favorites_count": { "type": ["integer", "null"] }, + "updated_at": { "type": ["string", "null"] },🤖 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 100 - 109, Replace deprecated "nullable": true with OpenAPI 3.1 union types for the affected schema properties: change "tags" to use "type": ["array","null"] (and keep "items": {"type":"string"}), change "creator" and "created_at" and "updated_at" to "type": ["string","null"], and change "favorites_count" to "type": ["integer","null"]; update the schemas where "nullable": true appears (fields: tags, creator, created_at, favorites_count, updated_at) and remove the "nullable" keys so the spec conforms to OpenAPI 3.1.
🤖 Prompt for all review comments with 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.
Nitpick comments:
In `@api-reference/openapi/agent-templates.json`:
- Around line 121-126: The AgentTemplatesError schema currently defines an
"error" property but doesn't guarantee its presence; update the
"AgentTemplatesError" schema to include a required array with "error" (i.e., add
"required": ["error"]) so API consumers and code generators can rely on the
field being present in 401/500 responses.
- Around line 107-109: The OpenAPI schema fields created_at and updated_at are
defined as nullable strings but should include format: "date-time"; update the
agent-templates.json entries for "created_at" and "updated_at" (keeping
nullable: true per the nullable refactor) to add format: "date-time" so
validators and generators treat them as ISO 8601 timestamps.
- Around line 17-42: The OpenAPI spec for the /api/agents/templates GET
currently returns an unbounded array of AgentTemplate; add pagination by
introducing query parameters (e.g., limit: integer, offset: integer OR cursor:
string) in the "parameters" array for that operation and replace the response
schema with a paginated wrapper (e.g., PaginatedAgentTemplateList) that includes
items: array of AgentTemplate, plus metadata fields like total_count,
next_cursor/next_page (and optionally page, per_page) so clients can page
results; update components/schemas to define the new paginated schema and ensure
the operation's description mentions default/maximum limits and behavior when
using cursor vs offset.
- Around line 100-109: Replace deprecated "nullable": true with OpenAPI 3.1
union types for the affected schema properties: change "tags" to use "type":
["array","null"] (and keep "items": {"type":"string"}), change "creator" and
"created_at" and "updated_at" to "type": ["string","null"], and change
"favorites_count" to "type": ["integer","null"]; update the schemas where
"nullable": true appears (fields: tags, creator, created_at, favorites_count,
updated_at) and remove the "nullable" keys so the spec conforms to OpenAPI 3.1.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: ffa95eb7-13ff-4471-a9bb-c97b0cbc298f
📒 Files selected for processing (3)
api-reference/agent-templates/list.mdxapi-reference/openapi/agent-templates.jsondocs.json
✅ Files skipped from review due to trivial changes (1)
- api-reference/agent-templates/list.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- docs.json
- Updated the description for the `/api/agents/templates` endpoint to remove redundant phrasing, enhancing clarity and readability for users accessing the API.
/api/agent-templatesendpoint, detailing the GET method, parameters, and response schemas for retrieving saved prompt templates.docs.jsonto include the new agent templates group.Summary by cubic
Adds docs for listing Agent Templates via GET
/api/agents/templatesand updates API reference navigation./api/agents/templates: nouserId;is_favouriteis required;shared_emailsonly for private templates owned by the caller (empty otherwise); supportsbearerAuthandapiKeyAuth; returns 200/401/500; refined endpoint description to remove redundant phrasing.docs.json: renamed "Agent Onboarding" to "Workflows" and added a "Templates" group with "List Agent Templates".Written for commit 9bb9098. Summary will update on new commits.
Summary by CodeRabbit