docs(agents): add agent templates endpoint reference#199
Conversation
📝 WalkthroughWalkthroughThis PR adds complete API reference documentation for Agent Templates endpoints. It introduces an OpenAPI v3.1.0 specification with five REST operations (list, create, update, delete, favorite), corresponding MDX documentation pages wired to those specifications, and navigation registration in docs.json. ChangesAgent Templates API Documentation
🎯 2 (Simple) | ⏱️ ~8 minutes Possibly Related PRs
Suggested Reviewers
🚥 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 |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
3 issues found across 7 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/agent-templates.json">
<violation number="1" location="api-reference/openapi/agent-templates.json:1">
P2: Custom agent: **Enforce Clear Code Style and Maintainability Practices**
File exceeds the custom <100 line limit for maintainability.</violation>
<violation number="2" location="api-reference/openapi/agent-templates.json:407">
P1: This OpenAPI 3.1 document uses `nullable`, which is not part of OAS 3.1 schema syntax; use JSON Schema null types instead.</violation>
<violation number="3" location="api-reference/openapi/agent-templates.json:517">
P2: `share_emails` is documented as optional but modeled as required in `CreateAgentTemplateRequest`, creating a contradictory API contract.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
| "schemas": { | ||
| "AgentTemplateCreator": { | ||
| "type": "object", | ||
| "nullable": true, |
There was a problem hiding this comment.
P1: This OpenAPI 3.1 document uses nullable, which is not part of OAS 3.1 schema syntax; use JSON Schema null types instead.
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 407:
<comment>This OpenAPI 3.1 document uses `nullable`, which is not part of OAS 3.1 schema syntax; use JSON Schema null types instead.</comment>
<file context>
@@ -0,0 +1,700 @@
+ "schemas": {
+ "AgentTemplateCreator": {
+ "type": "object",
+ "nullable": true,
+ "description": "The account that created the template. May be null when the creator account is unavailable.",
+ "required": [
</file context>
| @@ -0,0 +1,700 @@ | |||
| { | |||
There was a problem hiding this comment.
P2: Custom agent: Enforce Clear Code Style and Maintainability Practices
File exceeds the custom <100 line limit for maintainability.
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 1:
<comment>File exceeds the custom <100 line limit for maintainability.</comment>
<file context>
@@ -0,0 +1,700 @@
+{
+ "openapi": "3.1.0",
+ "info": {
</file context>
Rendered docs previewLocal Mintlify build of the five agent-templates endpoint pages. GET /api/agent-templates — List
POST /api/agent-templates — Create
PATCH /api/agent-templates/{id} — Update
DELETE /api/agent-templates/{id} — Delete
PUT /api/agent-templates/{id}/favorite — Toggle favoriteResponse tabs now show 403 (private template, no access) and 404 (not found) from the visibility check added in the api refactor. Screenshots hosted on the orphan branch |
| ] | ||
| }, | ||
| { | ||
| "group": "Agent Templates", |
There was a problem hiding this comment.
KISS principle
| "group": "Agent Templates", | |
| "group": "Templates", |
Documents the new dedicated api endpoints for CHAT_API_MIGRATION Group 7. Adds an "Agent Templates" group under Agents & Sandboxes with 5 endpoint pages backed by a new agent-templates.json OpenAPI spec. Endpoints support both x-api-key and Bearer auth; ownership is enforced server-side on PATCH/DELETE. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Mark tags / favorites_count / created_at non-nullable (matches DB
schema and the SDK-derived response shape)
- Add tags, creator, favorites_count, created_at, updated_at to
AgentTemplate.required (always returned)
- Add name, image, is_admin to AgentTemplateCreator.required (always
present in the flat block)
- Drop share_emails from CreateAgentTemplateRequest.required (zod
default makes it optional)
- Document 403 and 404 on PUT /api/agent-templates/{id}/favorite —
the visibility check (own / public / shared) was added in the api
refactor
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
sweetmantech
force-pushed
the
docs/agent-templates
branch
from
ef27645 to
84822b6
Compare
Applies sweetmantech's suggestion on PR #199 — the group is already nested inside the Agents-related tab, so "Templates" alone keeps the nav scannable. KISS. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 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/update.mdx`:
- Line 3: The frontmatter currently uses "openapi:
'/api-reference/openapi/agent-templates.json PATCH /api/agent-templates/{id}'"
which mixes the spec path and operation; update the openapi frontmatter to
contain only the operation signature "PATCH /api/agent-templates/{id}" so it
conforms to the repo-standard openapi format (look for the openapi frontmatter
key and replace its value with the METHOD /path string).
In `@api-reference/openapi/agent-templates.json`:
- Line 427: Replace all schema instances that use the removed OpenAPI 3.1
keyword "nullable": true with JSON Schema type unions: remove the nullable
property and add an explicit "type" array. Specifically, change the object
schema to "type": ["object", "null"] and the three string schemas to "type":
["string", "null"]; ensure you remove the nullable key entirely and keep any
other schema properties intact so the document conforms to OpenAPI 3.1 JSON
Schema semantics.
- Around line 16-23: The operation- and top-level "security" arrays currently
list separate objects (apiKeyAuth OR bearerAuth) which OpenAPI interprets as
alternatives; to require both credentials combine them into a single requirement
object so the array contains one object with both keys (e.g., [ { "apiKeyAuth":
[], "bearerAuth": [] } ]). Update the top-level "security" block and each
per-operation "security" block (or remove the per-operation blocks to inherit
the corrected top-level block) so they use the combined object instead of two
separate objects.
🪄 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: ea231504-eafc-477d-bbea-d790ad84ccfc
📒 Files selected for processing (7)
api-reference/agent-templates/create.mdxapi-reference/agent-templates/delete.mdxapi-reference/agent-templates/favorite.mdxapi-reference/agent-templates/list.mdxapi-reference/agent-templates/update.mdxapi-reference/openapi/agent-templates.jsondocs.json
| "security": [ | ||
| { | ||
| "apiKeyAuth": [] | ||
| }, | ||
| { | ||
| "bearerAuth": [] | ||
| } | ||
| ], |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
In OpenAPI 3.1, does security: [{apiKeyAuth: []}, {bearerAuth: []}]mean OR, and issecurity: [{apiKeyAuth: [], bearerAuth: []}] the correct way to require both?
💡 Result:
Yes, in OpenAPI 3.1, security: [{apiKeyAuth: []}, {bearerAuth: []}] means OR (either apiKeyAuth or bearerAuth satisfies the requirement), as the array elements are alternative security requirement objects where only one needs to be satisfied [1][2][3]. No, security: [{apiKeyAuth: [], bearerAuth: []}] is the correct way to require both (AND logic within a single security requirement object) [4][5][6].
Citations:
- 1: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md
- 2: https://spec.openapis.org/oas/v3.1.0.html
- 3: https://swagger.io/specification/
- 4: https://swagger.io/docs/specification/v3_0/authentication
- 5: https://stackoverflow.com/questions/30941901/swagger-adding-multiple-security-parameters-to-the-same-schema-definition
- 6: https://tyk.io/docs/basic-config-and-security/security/authentication-authorization/multiple-auth
🏁 Script executed:
# Check if the file exists and inspect the security blocks at mentioned lines
if [ -f "api-reference/openapi/agent-templates.json" ]; then
echo "=== File found. Inspecting security blocks at mentioned lines ==="
cat -n "api-reference/openapi/agent-templates.json" | sed -n '16,23p'
echo ""
echo "=== Lines 29-35 ==="
cat -n "api-reference/openapi/agent-templates.json" | sed -n '29,35p'
echo ""
echo "=== Lines 73-79 ==="
cat -n "api-reference/openapi/agent-templates.json" | sed -n '73,79p'
echo ""
echo "=== Lines 140-146 ==="
cat -n "api-reference/openapi/agent-templates.json" | sed -n '140,146p'
echo ""
echo "=== Lines 237-243 ==="
cat -n "api-reference/openapi/agent-templates.json" | sed -n '237,243p'
echo ""
echo "=== Lines 315-321 ==="
cat -n "api-reference/openapi/agent-templates.json" | sed -n '315,321p'
else
echo "File not found at api-reference/openapi/agent-templates.json"
# Try to locate it
find . -name "agent-templates.json" 2>/dev/null
fiRepository: recoupable/docs
Length of output: 1274
🏁 Script executed:
# Also check the openapi version and overall structure to understand context
if [ -f "api-reference/openapi/agent-templates.json" ]; then
echo "=== OpenAPI Version and Info ==="
head -20 "api-reference/openapi/agent-templates.json" | grep -E '"openapi"|"title"|"description"' || head -20 "api-reference/openapi/agent-templates.json"
fiRepository: recoupable/docs
Length of output: 367
🏁 Script executed:
# Check if there's any documentation about authentication requirements
# Search for comments or descriptions mentioning authentication, bearer, or apiKey
rg -i "authentication|bearer|apikey" "api-reference/openapi/agent-templates.json" -A 2 -B 2Repository: recoupable/docs
Length of output: 1095
🏁 Script executed:
# Also check the components section to see how these auth schemes are defined
grep -n "components\|securitySchemes\|apiKeyAuth\|bearerAuth" "api-reference/openapi/agent-templates.json" | head -30Repository: recoupable/docs
Length of output: 1759
Security requirements currently document API key OR bearer, not API key AND bearer.
Line 16 and repeated operation blocks use separate security requirement objects, which in OpenAPI are treated as alternatives. If both credentials are required together, this is misdocumented.
Suggested change
- "security": [
- { "apiKeyAuth": [] },
- { "bearerAuth": [] }
- ],
+ "security": [
+ { "apiKeyAuth": [], "bearerAuth": [] }
+ ],Apply the same change to each operation-level security block at lines 29–35, 73–79, 140–146, 237–243, and 315–321 (or remove per-operation blocks and inherit from top-level if identical).
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "security": [ | |
| { | |
| "apiKeyAuth": [] | |
| }, | |
| { | |
| "bearerAuth": [] | |
| } | |
| ], | |
| "security": [ | |
| { | |
| "apiKeyAuth": [], | |
| "bearerAuth": [] | |
| } | |
| ], |
🤖 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 16 - 23, The
operation- and top-level "security" arrays currently list separate objects
(apiKeyAuth OR bearerAuth) which OpenAPI interprets as alternatives; to require
both credentials combine them into a single requirement object so the array
contains one object with both keys (e.g., [ { "apiKeyAuth": [], "bearerAuth": []
} ]). Update the top-level "security" block and each per-operation "security"
block (or remove the per-operation blocks to inherit the corrected top-level
block) so they use the combined object instead of two separate objects.
Aligns with the existing /api/agents/* namespacing convention so the nav, the spec, and the public URL all read as templates living under the agents resource — not as a parallel top-level resource. Updates 3 path keys in agent-templates.json and the openapi: frontmatter in all 5 MDX pages (list, create, update, delete, favorite). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Folder: api-reference/agent-templates/ → api-reference/templates/
OpenAPI: openapi/agent-templates.json → openapi/templates.json
URL prefix: /api/agents/templates → /api/templates (matches api PR
recoupable/api#543; both use /api/templates throughout)
Schemas: AgentTemplate* → Template*
Page titles + descriptions: "agent template" → "template"
docs.json: navigation paths updated to api-reference/templates/*
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
URL: /api/templates → /api/agents/templates in OpenAPI paths and MDX frontmatter. Tracks the api PR (recoupable/api#543). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…e unions The spec declares openapi: 3.1.0, which removed the "nullable" keyword. Switch to JSON Schema type arrays: TemplateCreator object → ["object", "null"] TemplateCreator.name string → ["string", "null"] TemplateCreator.image string → ["string", "null"] Template.updated_at string (date) → ["string", "null"] Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2 participants
Documents 5 newly-migrated agent template endpoints — list / create / update / delete plus toggle favorite — backed by a new
agent-templates.jsonOpenAPI spec under a new "Agent Templates" group in the Agents & Sandboxes tab. Pairs with recoupable/api#543.Test plan
npx mintlify@latest devand verify the 5 new pages render with correct schemas, examples, and 2xx/4xx response shapes🤖 Generated with Claude Code
Summary by cubic
Adds API docs for Templates (list, create, update, delete, favorite) under a new "Templates" group. Endpoints live at
/api/agents/templateswith a new spec atapi-reference/openapi/templates.json.openapi/templates.jsonand 5 endpoints at/api/agents/templateswithx-api-keyand Bearer auth; favorite documents 403/404; PATCH/DELETE require ownership.api-reference/templates/*and a "Templates" group indocs.json; schemas aligned with API and OpenAPI 3.1: non-nulltags/favorites_count/created_at; requiredtags/creator/favorites_count/created_at/updated_at; use type unions (notnullable) forTemplateCreator, creatorname/image, andupdated_at;share_emailsoptional.Written for commit d9d6820. Summary will update on new commits.
Summary by CodeRabbit
Release Notes