Skip to content

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

Open
ahmednahima0-beep wants to merge 8 commits into
mainfrom
docs/agent-templates-get-endpoint
Open

docs: add agent templates section and endpoint for listing templates#197
ahmednahima0-beep wants to merge 8 commits into
mainfrom
docs/agent-templates-get-endpoint

Conversation

@ahmednahima0-beep
Copy link
Copy Markdown
Collaborator

@ahmednahima0-beep ahmednahima0-beep commented May 9, 2026

  • 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.

Summary by cubic

Adds docs for listing Agent Templates via GET /api/agents/templates and updates API reference navigation.

  • New Features
    • Added OpenAPI spec and docs page for GET /api/agents/templates: no userId; is_favourite is required; shared_emails only for private templates owned by the caller (empty otherwise); supports bearerAuth and apiKeyAuth; returns 200/401/500; refined endpoint description to remove redundant phrasing.
    • Updated 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

  • Documentation
    • Added API reference for the "List Agent Templates" endpoint, including request/response details, authentication methods, and data schemas.
    • Added an "Agent Templates" (Templates) entry to the API navigation and renamed the previous "Agent Onboarding" group to "Workflows" for clearer organization.

Review Change Stack

- 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.
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 9, 2026

📝 Walkthrough

Walkthrough

Adds 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.

Changes

Agent Templates API Documentation

Layer / File(s) Summary
API Schema & Security Contracts
api-reference/openapi/agent-templates.json
OpenAPI metadata plus components.schemas.AgentTemplate and AgentTemplatesError; defines apiKeyAuth and bearerAuth security schemes.
GET /api/agents/templates Operation
api-reference/openapi/agent-templates.json
Defines GET /api/agents/templates with required authentication, no query parameters, and responses: 200 (array of AgentTemplate), 401, 500 (use AgentTemplatesError).
Documentation Page & Navigation
api-reference/agent-templates/list.mdx, docs.json
Adds MDX page "List Agent Templates" referencing the OpenAPI source and inserts a "Templates" group under "Agents & Sandboxes" linking the page.

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
Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

  • recoupable/docs#199: Overlapping changes that also add the OpenAPI spec and documentation for listing agent templates.
  • recoupable/docs#104: Related docs navigation edits and additional agent-related API pages.

Suggested reviewers

  • sweetmantech

Poem

🐰 I hopped a trail through spec and guide,
Pages wired to list templates wide,
Tokens and keys stand at the gate,
Responses map the templates' state,
Hooray — docs live, APIs abide!

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The pull request title accurately summarizes the main changes: adding a new agent templates documentation section and an OpenAPI endpoint for listing templates. It is concise, clear, and directly reflects the primary purpose of the changeset.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/agent-templates-get-endpoint

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

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

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

📥 Commits

Reviewing files that changed from the base of the PR and between 6c1b84b and 91a7e54.

📒 Files selected for processing (4)
  • api-reference/agent-templates/list.mdx
  • api-reference/openapi/agent-templates.json
  • api-reference/openapi/research.json
  • docs.json

Comment thread api-reference/agent-templates/list.mdx
Comment on lines +11 to +14
"servers": [
{
"url": "https://api.recoupable.com"
}
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.

⚠️ 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

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

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?

Comment thread api-reference/openapi/agent-templates.json Outdated
Comment thread api-reference/openapi/research.json Outdated
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

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

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.

Comment thread api-reference/openapi/research.json Outdated
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentTemplate"
Copy link
Copy Markdown

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

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

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!

},
"servers": [
{
"url": "https://api.recoupable.com"
Copy link
Copy Markdown

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

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

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.

…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.
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

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

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.

Comment thread api-reference/openapi/agent-templates.json Outdated
- 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.
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

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

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.

Comment thread api-reference/openapi/agent-templates.json Outdated
- 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.
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

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

🧹 Nitpick comments (1)
api-reference/openapi/agent-templates.json (1)

34-39: ⚡ Quick win

Add maxItems constraints to array schemas.

The response array and nested array properties (tags, shared_emails) lack maxItems constraints, 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)
  • tags array (line 101): Limit to a reasonable number (e.g., 20 tags)
  • shared_emails array (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

📥 Commits

Reviewing files that changed from the base of the PR and between 91a7e54 and ae3ac5e.

📒 Files selected for processing (2)
  • api-reference/agent-templates/list.mdx
  • api-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.",
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

KISS principle.

Suggested change
"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.",

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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.
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

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

🧹 Nitpick comments (4)
api-reference/openapi/agent-templates.json (4)

121-126: ⚡ Quick win

Mark error as required in the error schema.

The AgentTemplatesError schema should mark error as 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 win

Add format: "date-time" to timestamp fields.

The created_at and updated_at fields are documented as strings but likely represent ISO 8601 timestamps. Adding format: "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 win

Consider 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 win

Replace deprecated nullable: true with OpenAPI 3.1 type arrays.

OpenAPI 3.1 replaced the nullable keyword with union types. Lines 103, 105, 107, 108, and 109 use nullable: 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

📥 Commits

Reviewing files that changed from the base of the PR and between ae3ac5e and 4b1060c.

📒 Files selected for processing (3)
  • api-reference/agent-templates/list.mdx
  • api-reference/openapi/agent-templates.json
  • docs.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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants