From 0a0a9e47dad3ef231839259213cac2ee2caed6c0 Mon Sep 17 00:00:00 2001
From: Arpit Gupta <arpitgupta1214@gmail.com>
Date: Sat, 9 May 2026 22:58:35 +0530
Subject: [PATCH 1/7] docs: add agent templates endpoints
 (list/create/update/delete/favorite)

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>
---
 api-reference/agent-templates/create.mdx   |   4 +
 api-reference/agent-templates/delete.mdx   |   4 +
 api-reference/agent-templates/favorite.mdx |   4 +
 api-reference/agent-templates/list.mdx     |   4 +
 api-reference/agent-templates/update.mdx   |   4 +
 api-reference/openapi/agent-templates.json | 700 +++++++++++++++++++++
 docs.json                                  |  10 +
 7 files changed, 730 insertions(+)
 create mode 100644 api-reference/agent-templates/create.mdx
 create mode 100644 api-reference/agent-templates/delete.mdx
 create mode 100644 api-reference/agent-templates/favorite.mdx
 create mode 100644 api-reference/agent-templates/list.mdx
 create mode 100644 api-reference/agent-templates/update.mdx
 create mode 100644 api-reference/openapi/agent-templates.json

diff --git a/api-reference/agent-templates/create.mdx b/api-reference/agent-templates/create.mdx
new file mode 100644
index 0000000..bfe6722
--- /dev/null
+++ b/api-reference/agent-templates/create.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Create Agent Template'
+openapi: '/api-reference/openapi/agent-templates.json POST /api/agent-templates'
+---
diff --git a/api-reference/agent-templates/delete.mdx b/api-reference/agent-templates/delete.mdx
new file mode 100644
index 0000000..f95b9f7
--- /dev/null
+++ b/api-reference/agent-templates/delete.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Delete Agent Template'
+openapi: '/api-reference/openapi/agent-templates.json DELETE /api/agent-templates/{id}'
+---
diff --git a/api-reference/agent-templates/favorite.mdx b/api-reference/agent-templates/favorite.mdx
new file mode 100644
index 0000000..e699a5f
--- /dev/null
+++ b/api-reference/agent-templates/favorite.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Favorite Agent Template'
+openapi: '/api-reference/openapi/agent-templates.json PUT /api/agent-templates/{id}/favorite'
+---
diff --git a/api-reference/agent-templates/list.mdx b/api-reference/agent-templates/list.mdx
new file mode 100644
index 0000000..04adc3a
--- /dev/null
+++ b/api-reference/agent-templates/list.mdx
@@ -0,0 +1,4 @@
+---
+title: 'List Agent Templates'
+openapi: '/api-reference/openapi/agent-templates.json GET /api/agent-templates'
+---
diff --git a/api-reference/agent-templates/update.mdx b/api-reference/agent-templates/update.mdx
new file mode 100644
index 0000000..6a01bc8
--- /dev/null
+++ b/api-reference/agent-templates/update.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Update Agent Template'
+openapi: '/api-reference/openapi/agent-templates.json PATCH /api/agent-templates/{id}'
+---
diff --git a/api-reference/openapi/agent-templates.json b/api-reference/openapi/agent-templates.json
new file mode 100644
index 0000000..3cbeff6
--- /dev/null
+++ b/api-reference/openapi/agent-templates.json
@@ -0,0 +1,700 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Recoup API - Agent Templates",
+    "description": "API documentation for managing reusable agent templates on the Recoup platform. Templates capture a prompt, description, and tags that can be shared with other accounts or kept private.",
+    "license": {
+      "name": "MIT"
+    },
+    "version": "1.0.0"
+  },
+  "servers": [
+    {
+      "url": "https://api.recoupable.com"
+    }
+  ],
+  "security": [
+    {
+      "apiKeyAuth": []
+    },
+    {
+      "bearerAuth": []
+    }
+  ],
+  "paths": {
+    "/api/agent-templates": {
+      "get": {
+        "summary": "List agent templates",
+        "description": "Retrieve every agent template visible to the authenticated account. The response combines templates the account owns, public templates created by other accounts, and private templates that have been shared with the authenticated account's email.",
+        "security": [
+          {
+            "apiKeyAuth": []
+          },
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Templates retrieved successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ListAgentTemplatesResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized - missing or invalid credentials",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "summary": "Create an agent template",
+        "description": "Create a new agent template owned by the authenticated account. When `is_private` is true, the optional `share_emails` array grants explicit read access to the listed accounts; for public templates the field is ignored.",
+        "security": [
+          {
+            "apiKeyAuth": []
+          },
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "description": "Agent template fields",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateAgentTemplateRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Template created successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AgentTemplateResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request - validation failed or required fields missing",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized - missing or invalid credentials",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/agent-templates/{id}": {
+      "patch": {
+        "summary": "Update an agent template",
+        "description": "Update fields on an existing agent template owned by the authenticated account. All body fields are optional and only the supplied fields are modified. Providing `share_emails` replaces the existing share list for the template.",
+        "security": [
+          {
+            "apiKeyAuth": []
+          },
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "The unique identifier (UUID) of the agent template to update",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "description": "Fields to update on the template",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateAgentTemplateRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Template updated successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AgentTemplateResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request - validation failed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized - missing or invalid credentials",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden - the authenticated account does not own this template",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Template not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "summary": "Delete an agent template",
+        "description": "Permanently delete an agent template. Only the owner of the template may perform this action. Associated share records and favorite entries are removed as part of the deletion.",
+        "security": [
+          {
+            "apiKeyAuth": []
+          },
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "The unique identifier (UUID) of the agent template to delete",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Template deleted successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SuccessResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized - missing or invalid credentials",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden - the authenticated account does not own this template",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Template not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/agent-templates/{id}/favorite": {
+      "put": {
+        "summary": "Toggle favorite on an agent template",
+        "description": "Mark or unmark an agent template as a favorite for the authenticated account. The endpoint is idempotent - calling it repeatedly with the same `is_favourite` value has no additional effect.",
+        "security": [
+          {
+            "apiKeyAuth": []
+          },
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "The unique identifier (UUID) of the agent template to favorite or unfavorite",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "description": "Desired favorite state",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ToggleFavoriteRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Favorite state updated successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SuccessResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request - validation failed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized - missing or invalid credentials",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "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": {
+      "AgentTemplateCreator": {
+        "type": "object",
+        "nullable": true,
+        "description": "The account that created the template. May be null when the creator account is unavailable.",
+        "required": [
+          "id"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Unique identifier of the creator account"
+          },
+          "name": {
+            "type": "string",
+            "nullable": true,
+            "description": "Display name of the creator account"
+          },
+          "image": {
+            "type": "string",
+            "nullable": true,
+            "description": "Profile image URL of the creator account"
+          },
+          "is_admin": {
+            "type": "boolean",
+            "description": "Whether the creator is a Recoup admin"
+          }
+        }
+      },
+      "AgentTemplate": {
+        "type": "object",
+        "required": [
+          "id",
+          "title",
+          "description",
+          "prompt",
+          "is_private",
+          "is_favourite",
+          "shared_emails"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Unique identifier of the agent template"
+          },
+          "title": {
+            "type": "string",
+            "description": "Short human-readable title for the template (3-50 characters)"
+          },
+          "description": {
+            "type": "string",
+            "description": "Description of what the template does (10-200 characters)"
+          },
+          "prompt": {
+            "type": "string",
+            "description": "The agent prompt body (20-10000 characters)"
+          },
+          "tags": {
+            "type": "array",
+            "nullable": true,
+            "items": {
+              "type": "string"
+            },
+            "description": "Free-form tags used to categorize the template"
+          },
+          "creator": {
+            "$ref": "#/components/schemas/AgentTemplateCreator"
+          },
+          "is_private": {
+            "type": "boolean",
+            "description": "Whether the template is restricted to the creator and explicitly shared accounts"
+          },
+          "is_favourite": {
+            "type": "boolean",
+            "description": "Whether the authenticated account has favorited this template"
+          },
+          "favorites_count": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Total number of accounts that have favorited this template"
+          },
+          "shared_emails": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "email"
+            },
+            "description": "Emails that have explicit access to a private template. Empty for public templates."
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true,
+            "description": "ISO 8601 timestamp of when the template was created"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true,
+            "description": "ISO 8601 timestamp of when the template was last updated"
+          }
+        }
+      },
+      "CreateAgentTemplateRequest": {
+        "type": "object",
+        "required": [
+          "title",
+          "description",
+          "prompt",
+          "tags",
+          "is_private",
+          "share_emails"
+        ],
+        "properties": {
+          "title": {
+            "type": "string",
+            "minLength": 3,
+            "maxLength": 50,
+            "description": "Short human-readable title for the template"
+          },
+          "description": {
+            "type": "string",
+            "minLength": 10,
+            "maxLength": 200,
+            "description": "Description of what the template does"
+          },
+          "prompt": {
+            "type": "string",
+            "minLength": 20,
+            "maxLength": 10000,
+            "description": "The agent prompt body"
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Free-form tags used to categorize the template. Pass an empty array if there are no tags."
+          },
+          "is_private": {
+            "type": "boolean",
+            "description": "When true, the template is restricted to the creator and the accounts listed in `share_emails`"
+          },
+          "share_emails": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "email"
+            },
+            "description": "Emails to grant access to. Only applied when `is_private` is true. Pass an empty array when there are no shares."
+          }
+        }
+      },
+      "UpdateAgentTemplateRequest": {
+        "type": "object",
+        "description": "All fields are optional. Only supplied fields are updated.",
+        "properties": {
+          "title": {
+            "type": "string",
+            "minLength": 3,
+            "maxLength": 50,
+            "description": "Short human-readable title for the template"
+          },
+          "description": {
+            "type": "string",
+            "minLength": 10,
+            "maxLength": 200,
+            "description": "Description of what the template does"
+          },
+          "prompt": {
+            "type": "string",
+            "minLength": 20,
+            "maxLength": 10000,
+            "description": "The agent prompt body"
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Free-form tags used to categorize the template. Pass an empty array to clear tags."
+          },
+          "is_private": {
+            "type": "boolean",
+            "description": "When true, the template is restricted to the creator and the accounts listed in `share_emails`"
+          },
+          "share_emails": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "email"
+            },
+            "description": "Replaces the existing share list for the template. Only applied when the template is (or becomes) private."
+          }
+        }
+      },
+      "ToggleFavoriteRequest": {
+        "type": "object",
+        "required": [
+          "is_favourite"
+        ],
+        "properties": {
+          "is_favourite": {
+            "type": "boolean",
+            "description": "Desired favorite state for the authenticated account"
+          }
+        }
+      },
+      "ListAgentTemplatesResponse": {
+        "type": "object",
+        "required": [
+          "status",
+          "templates"
+        ],
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "success"
+            ],
+            "description": "Status of the request"
+          },
+          "templates": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AgentTemplate"
+            },
+            "description": "Templates accessible to the authenticated account (own, public, and shared)"
+          }
+        }
+      },
+      "AgentTemplateResponse": {
+        "type": "object",
+        "required": [
+          "status",
+          "template"
+        ],
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "success"
+            ],
+            "description": "Status of the request"
+          },
+          "template": {
+            "$ref": "#/components/schemas/AgentTemplate"
+          }
+        }
+      },
+      "SuccessResponse": {
+        "type": "object",
+        "required": [
+          "status"
+        ],
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "success"
+            ],
+            "description": "Status of the request"
+          }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "required": [
+          "status",
+          "error"
+        ],
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "error"
+            ],
+            "description": "Status of the request"
+          },
+          "error": {
+            "type": "string",
+            "description": "Human-readable error message"
+          },
+          "missing_fields": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Names of required fields that were missing from the request, when applicable"
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/docs.json b/docs.json
index 458ada9..2fb04e8 100644
--- a/docs.json
+++ b/docs.json
@@ -242,6 +242,16 @@
               "content-agent"
             ]
           },
+          {
+            "group": "Agent Templates",
+            "pages": [
+              "api-reference/agent-templates/list",
+              "api-reference/agent-templates/create",
+              "api-reference/agent-templates/update",
+              "api-reference/agent-templates/delete",
+              "api-reference/agent-templates/favorite"
+            ]
+          },
           {
             "group": "Tasks",
             "pages": [

From 84822b69bf6f74bc28a23243dc4ea3c9d604dfea Mon Sep 17 00:00:00 2001
From: Arpit Gupta <arpitgupta1214@gmail.com>
Date: Tue, 12 May 2026 02:00:09 +0530
Subject: [PATCH 2/7] docs(agent-templates): align openapi with post-refactor
 api shape
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 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>
---
 api-reference/openapi/agent-templates.json | 48 ++++++++++++++++------
 1 file changed, 36 insertions(+), 12 deletions(-)

diff --git a/api-reference/openapi/agent-templates.json b/api-reference/openapi/agent-templates.json
index 3cbeff6..84ffb56 100644
--- a/api-reference/openapi/agent-templates.json
+++ b/api-reference/openapi/agent-templates.json
@@ -311,7 +311,7 @@
     "/api/agent-templates/{id}/favorite": {
       "put": {
         "summary": "Toggle favorite on an agent template",
-        "description": "Mark or unmark an agent template as a favorite for the authenticated account. The endpoint is idempotent - calling it repeatedly with the same `is_favourite` value has no additional effect.",
+        "description": "Mark or unmark an agent template as a favorite for the authenticated account. The endpoint is idempotent - calling it repeatedly with the same `is_favourite` value has no additional effect. The caller must be able to see the template (own it, the template is public, or it has been shared with them).",
         "security": [
           {
             "apiKeyAuth": []
@@ -374,6 +374,26 @@
               }
             }
           },
+          "403": {
+            "description": "Forbidden - the template is private and has not been shared with the authenticated account",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Template not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
           "500": {
             "description": "Internal server error",
             "content": {
@@ -407,7 +427,10 @@
         "nullable": true,
         "description": "The account that created the template. May be null when the creator account is unavailable.",
         "required": [
-          "id"
+          "id",
+          "name",
+          "image",
+          "is_admin"
         ],
         "properties": {
           "id": {
@@ -427,7 +450,7 @@
           },
           "is_admin": {
             "type": "boolean",
-            "description": "Whether the creator is a Recoup admin"
+            "description": "Whether the creator is a Recoup admin (their account email is on the platform admin allow-list)"
           }
         }
       },
@@ -438,9 +461,14 @@
           "title",
           "description",
           "prompt",
+          "tags",
+          "creator",
           "is_private",
           "is_favourite",
-          "shared_emails"
+          "favorites_count",
+          "shared_emails",
+          "created_at",
+          "updated_at"
         ],
         "properties": {
           "id": {
@@ -462,11 +490,10 @@
           },
           "tags": {
             "type": "array",
-            "nullable": true,
             "items": {
               "type": "string"
             },
-            "description": "Free-form tags used to categorize the template"
+            "description": "Free-form tags used to categorize the template. Empty array when there are no tags."
           },
           "creator": {
             "$ref": "#/components/schemas/AgentTemplateCreator"
@@ -481,7 +508,6 @@
           },
           "favorites_count": {
             "type": "integer",
-            "nullable": true,
             "description": "Total number of accounts that have favorited this template"
           },
           "shared_emails": {
@@ -490,12 +516,11 @@
               "type": "string",
               "format": "email"
             },
-            "description": "Emails that have explicit access to a private template. Empty for public templates."
+            "description": "Emails the template has been shared with. Only populated for private templates the authenticated account owns; empty for public templates and for private templates shared with the caller."
           },
           "created_at": {
             "type": "string",
             "format": "date-time",
-            "nullable": true,
             "description": "ISO 8601 timestamp of when the template was created"
           },
           "updated_at": {
@@ -513,8 +538,7 @@
           "description",
           "prompt",
           "tags",
-          "is_private",
-          "share_emails"
+          "is_private"
         ],
         "properties": {
           "title": {
@@ -552,7 +576,7 @@
               "type": "string",
               "format": "email"
             },
-            "description": "Emails to grant access to. Only applied when `is_private` is true. Pass an empty array when there are no shares."
+            "description": "Emails to grant access to. Only applied when `is_private` is true. Defaults to an empty array when omitted."
           }
         }
       },

From 6c889650c4535830a75f7a9a62b0858d990a7b4b Mon Sep 17 00:00:00 2001
From: Sweets Sweetman <sweetmantech@gmail.com>
Date: Mon, 11 May 2026 19:24:10 -0500
Subject: [PATCH 3/7] =?UTF-8?q?docs:=20rename=20nav=20group=20Agent=20Temp?=
 =?UTF-8?q?lates=20=E2=86=92=20Templates=20per=20review?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 docs.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs.json b/docs.json
index 2fb04e8..4c1cf94 100644
--- a/docs.json
+++ b/docs.json
@@ -243,7 +243,7 @@
             ]
           },
           {
-            "group": "Agent Templates",
+            "group": "Templates",
             "pages": [
               "api-reference/agent-templates/list",
               "api-reference/agent-templates/create",

From fc4692428b6812351ed4bb4cec74aa25830fdb67 Mon Sep 17 00:00:00 2001
From: Sweets Sweetman <sweetmantech@gmail.com>
Date: Mon, 11 May 2026 19:26:06 -0500
Subject: [PATCH 4/7] =?UTF-8?q?docs:=20rename=20routes=20/api/agent-templa?=
 =?UTF-8?q?tes=20=E2=86=92=20/api/agents/templates?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 api-reference/agent-templates/create.mdx   | 2 +-
 api-reference/agent-templates/delete.mdx   | 2 +-
 api-reference/agent-templates/favorite.mdx | 2 +-
 api-reference/agent-templates/list.mdx     | 2 +-
 api-reference/agent-templates/update.mdx   | 2 +-
 api-reference/openapi/agent-templates.json | 6 +++---
 6 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/api-reference/agent-templates/create.mdx b/api-reference/agent-templates/create.mdx
index bfe6722..a40ef1d 100644
--- a/api-reference/agent-templates/create.mdx
+++ b/api-reference/agent-templates/create.mdx
@@ -1,4 +1,4 @@
 ---
 title: 'Create Agent Template'
-openapi: '/api-reference/openapi/agent-templates.json POST /api/agent-templates'
+openapi: '/api-reference/openapi/agent-templates.json POST /api/agents/templates'
 ---
diff --git a/api-reference/agent-templates/delete.mdx b/api-reference/agent-templates/delete.mdx
index f95b9f7..737ad4a 100644
--- a/api-reference/agent-templates/delete.mdx
+++ b/api-reference/agent-templates/delete.mdx
@@ -1,4 +1,4 @@
 ---
 title: 'Delete Agent Template'
-openapi: '/api-reference/openapi/agent-templates.json DELETE /api/agent-templates/{id}'
+openapi: '/api-reference/openapi/agent-templates.json DELETE /api/agents/templates/{id}'
 ---
diff --git a/api-reference/agent-templates/favorite.mdx b/api-reference/agent-templates/favorite.mdx
index e699a5f..cd93982 100644
--- a/api-reference/agent-templates/favorite.mdx
+++ b/api-reference/agent-templates/favorite.mdx
@@ -1,4 +1,4 @@
 ---
 title: 'Favorite Agent Template'
-openapi: '/api-reference/openapi/agent-templates.json PUT /api/agent-templates/{id}/favorite'
+openapi: '/api-reference/openapi/agent-templates.json PUT /api/agents/templates/{id}/favorite'
 ---
diff --git a/api-reference/agent-templates/list.mdx b/api-reference/agent-templates/list.mdx
index 04adc3a..2295ea3 100644
--- a/api-reference/agent-templates/list.mdx
+++ b/api-reference/agent-templates/list.mdx
@@ -1,4 +1,4 @@
 ---
 title: 'List Agent Templates'
-openapi: '/api-reference/openapi/agent-templates.json GET /api/agent-templates'
+openapi: '/api-reference/openapi/agent-templates.json GET /api/agents/templates'
 ---
diff --git a/api-reference/agent-templates/update.mdx b/api-reference/agent-templates/update.mdx
index 6a01bc8..b836547 100644
--- a/api-reference/agent-templates/update.mdx
+++ b/api-reference/agent-templates/update.mdx
@@ -1,4 +1,4 @@
 ---
 title: 'Update Agent Template'
-openapi: '/api-reference/openapi/agent-templates.json PATCH /api/agent-templates/{id}'
+openapi: '/api-reference/openapi/agent-templates.json PATCH /api/agents/templates/{id}'
 ---
diff --git a/api-reference/openapi/agent-templates.json b/api-reference/openapi/agent-templates.json
index 84ffb56..597f715 100644
--- a/api-reference/openapi/agent-templates.json
+++ b/api-reference/openapi/agent-templates.json
@@ -22,7 +22,7 @@
     }
   ],
   "paths": {
-    "/api/agent-templates": {
+    "/api/agents/templates": {
       "get": {
         "summary": "List agent templates",
         "description": "Retrieve every agent template visible to the authenticated account. The response combines templates the account owns, public templates created by other accounts, and private templates that have been shared with the authenticated account's email.",
@@ -133,7 +133,7 @@
         }
       }
     },
-    "/api/agent-templates/{id}": {
+    "/api/agents/templates/{id}": {
       "patch": {
         "summary": "Update an agent template",
         "description": "Update fields on an existing agent template owned by the authenticated account. All body fields are optional and only the supplied fields are modified. Providing `share_emails` replaces the existing share list for the template.",
@@ -308,7 +308,7 @@
         }
       }
     },
-    "/api/agent-templates/{id}/favorite": {
+    "/api/agents/templates/{id}/favorite": {
       "put": {
         "summary": "Toggle favorite on an agent template",
         "description": "Mark or unmark an agent template as a favorite for the authenticated account. The endpoint is idempotent - calling it repeatedly with the same `is_favourite` value has no additional effect. The caller must be able to see the template (own it, the template is public, or it has been shared with them).",

From b02517fdeb25fb234169b6ed23d8de7203d24208 Mon Sep 17 00:00:00 2001
From: Arpit Gupta <arpitgupta1214@gmail.com>
Date: Tue, 12 May 2026 06:04:00 +0530
Subject: [PATCH 5/7] docs(templates): finish rename, align with api PR
 /api/templates URL
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 api-reference/agent-templates/create.mdx      |  4 --
 api-reference/agent-templates/delete.mdx      |  4 --
 api-reference/agent-templates/favorite.mdx    |  4 --
 api-reference/agent-templates/list.mdx        |  4 --
 api-reference/agent-templates/update.mdx      |  4 --
 .../{agent-templates.json => templates.json}  | 68 +++++++++----------
 api-reference/templates/create.mdx            |  4 ++
 api-reference/templates/delete.mdx            |  4 ++
 api-reference/templates/favorite.mdx          |  4 ++
 api-reference/templates/list.mdx              |  4 ++
 api-reference/templates/update.mdx            |  4 ++
 docs.json                                     | 10 +--
 12 files changed, 59 insertions(+), 59 deletions(-)
 delete mode 100644 api-reference/agent-templates/create.mdx
 delete mode 100644 api-reference/agent-templates/delete.mdx
 delete mode 100644 api-reference/agent-templates/favorite.mdx
 delete mode 100644 api-reference/agent-templates/list.mdx
 delete mode 100644 api-reference/agent-templates/update.mdx
 rename api-reference/openapi/{agent-templates.json => templates.json} (86%)
 create mode 100644 api-reference/templates/create.mdx
 create mode 100644 api-reference/templates/delete.mdx
 create mode 100644 api-reference/templates/favorite.mdx
 create mode 100644 api-reference/templates/list.mdx
 create mode 100644 api-reference/templates/update.mdx

diff --git a/api-reference/agent-templates/create.mdx b/api-reference/agent-templates/create.mdx
deleted file mode 100644
index a40ef1d..0000000
--- a/api-reference/agent-templates/create.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: 'Create Agent Template'
-openapi: '/api-reference/openapi/agent-templates.json POST /api/agents/templates'
----
diff --git a/api-reference/agent-templates/delete.mdx b/api-reference/agent-templates/delete.mdx
deleted file mode 100644
index 737ad4a..0000000
--- a/api-reference/agent-templates/delete.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: 'Delete Agent Template'
-openapi: '/api-reference/openapi/agent-templates.json DELETE /api/agents/templates/{id}'
----
diff --git a/api-reference/agent-templates/favorite.mdx b/api-reference/agent-templates/favorite.mdx
deleted file mode 100644
index cd93982..0000000
--- a/api-reference/agent-templates/favorite.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: 'Favorite Agent Template'
-openapi: '/api-reference/openapi/agent-templates.json PUT /api/agents/templates/{id}/favorite'
----
diff --git a/api-reference/agent-templates/list.mdx b/api-reference/agent-templates/list.mdx
deleted file mode 100644
index 2295ea3..0000000
--- a/api-reference/agent-templates/list.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: 'List Agent Templates'
-openapi: '/api-reference/openapi/agent-templates.json GET /api/agents/templates'
----
diff --git a/api-reference/agent-templates/update.mdx b/api-reference/agent-templates/update.mdx
deleted file mode 100644
index b836547..0000000
--- a/api-reference/agent-templates/update.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: 'Update Agent Template'
-openapi: '/api-reference/openapi/agent-templates.json PATCH /api/agents/templates/{id}'
----
diff --git a/api-reference/openapi/agent-templates.json b/api-reference/openapi/templates.json
similarity index 86%
rename from api-reference/openapi/agent-templates.json
rename to api-reference/openapi/templates.json
index 597f715..bfb7353 100644
--- a/api-reference/openapi/agent-templates.json
+++ b/api-reference/openapi/templates.json
@@ -1,8 +1,8 @@
 {
   "openapi": "3.1.0",
   "info": {
-    "title": "Recoup API - Agent Templates",
-    "description": "API documentation for managing reusable agent templates on the Recoup platform. Templates capture a prompt, description, and tags that can be shared with other accounts or kept private.",
+    "title": "Recoup API - Templates",
+    "description": "API documentation for managing reusable templates on the Recoup platform. Templates capture a prompt, description, and tags that can be shared with other accounts or kept private.",
     "license": {
       "name": "MIT"
     },
@@ -22,10 +22,10 @@
     }
   ],
   "paths": {
-    "/api/agents/templates": {
+    "/api/templates": {
       "get": {
-        "summary": "List agent templates",
-        "description": "Retrieve every agent template visible to the authenticated account. The response combines templates the account owns, public templates created by other accounts, and private templates that have been shared with the authenticated account's email.",
+        "summary": "List templates",
+        "description": "Retrieve every template visible to the authenticated account. The response combines templates the account owns, public templates created by other accounts, and private templates that have been shared with the authenticated account's email.",
         "security": [
           {
             "apiKeyAuth": []
@@ -40,7 +40,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ListAgentTemplatesResponse"
+                  "$ref": "#/components/schemas/ListTemplatesResponse"
                 }
               }
             }
@@ -68,8 +68,8 @@
         }
       },
       "post": {
-        "summary": "Create an agent template",
-        "description": "Create a new agent template owned by the authenticated account. When `is_private` is true, the optional `share_emails` array grants explicit read access to the listed accounts; for public templates the field is ignored.",
+        "summary": "Create a template",
+        "description": "Create a new template owned by the authenticated account. When `is_private` is true, the optional `share_emails` array grants explicit read access to the listed accounts; for public templates the field is ignored.",
         "security": [
           {
             "apiKeyAuth": []
@@ -79,12 +79,12 @@
           }
         ],
         "requestBody": {
-          "description": "Agent template fields",
+          "description": "Template fields",
           "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/CreateAgentTemplateRequest"
+                "$ref": "#/components/schemas/CreateTemplateRequest"
               }
             }
           }
@@ -95,7 +95,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/AgentTemplateResponse"
+                  "$ref": "#/components/schemas/TemplateResponse"
                 }
               }
             }
@@ -133,10 +133,10 @@
         }
       }
     },
-    "/api/agents/templates/{id}": {
+    "/api/templates/{id}": {
       "patch": {
-        "summary": "Update an agent template",
-        "description": "Update fields on an existing agent template owned by the authenticated account. All body fields are optional and only the supplied fields are modified. Providing `share_emails` replaces the existing share list for the template.",
+        "summary": "Update a template",
+        "description": "Update fields on an existing template owned by the authenticated account. All body fields are optional and only the supplied fields are modified. Providing `share_emails` replaces the existing share list for the template.",
         "security": [
           {
             "apiKeyAuth": []
@@ -149,7 +149,7 @@
           {
             "name": "id",
             "in": "path",
-            "description": "The unique identifier (UUID) of the agent template to update",
+            "description": "The unique identifier (UUID) of the template to update",
             "required": true,
             "schema": {
               "type": "string",
@@ -163,7 +163,7 @@
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/UpdateAgentTemplateRequest"
+                "$ref": "#/components/schemas/UpdateTemplateRequest"
               }
             }
           }
@@ -174,7 +174,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/AgentTemplateResponse"
+                  "$ref": "#/components/schemas/TemplateResponse"
                 }
               }
             }
@@ -232,8 +232,8 @@
         }
       },
       "delete": {
-        "summary": "Delete an agent template",
-        "description": "Permanently delete an agent template. Only the owner of the template may perform this action. Associated share records and favorite entries are removed as part of the deletion.",
+        "summary": "Delete a template",
+        "description": "Permanently delete an template. Only the owner of the template may perform this action. Associated share records and favorite entries are removed as part of the deletion.",
         "security": [
           {
             "apiKeyAuth": []
@@ -246,7 +246,7 @@
           {
             "name": "id",
             "in": "path",
-            "description": "The unique identifier (UUID) of the agent template to delete",
+            "description": "The unique identifier (UUID) of the template to delete",
             "required": true,
             "schema": {
               "type": "string",
@@ -308,10 +308,10 @@
         }
       }
     },
-    "/api/agents/templates/{id}/favorite": {
+    "/api/templates/{id}/favorite": {
       "put": {
-        "summary": "Toggle favorite on an agent template",
-        "description": "Mark or unmark an agent template as a favorite for the authenticated account. The endpoint is idempotent - calling it repeatedly with the same `is_favourite` value has no additional effect. The caller must be able to see the template (own it, the template is public, or it has been shared with them).",
+        "summary": "Toggle favorite on a template",
+        "description": "Mark or unmark an template as a favorite for the authenticated account. The endpoint is idempotent - calling it repeatedly with the same `is_favourite` value has no additional effect. The caller must be able to see the template (own it, the template is public, or it has been shared with them).",
         "security": [
           {
             "apiKeyAuth": []
@@ -324,7 +324,7 @@
           {
             "name": "id",
             "in": "path",
-            "description": "The unique identifier (UUID) of the agent template to favorite or unfavorite",
+            "description": "The unique identifier (UUID) of the template to favorite or unfavorite",
             "required": true,
             "schema": {
               "type": "string",
@@ -422,7 +422,7 @@
       }
     },
     "schemas": {
-      "AgentTemplateCreator": {
+      "TemplateCreator": {
         "type": "object",
         "nullable": true,
         "description": "The account that created the template. May be null when the creator account is unavailable.",
@@ -454,7 +454,7 @@
           }
         }
       },
-      "AgentTemplate": {
+      "Template": {
         "type": "object",
         "required": [
           "id",
@@ -474,7 +474,7 @@
           "id": {
             "type": "string",
             "format": "uuid",
-            "description": "Unique identifier of the agent template"
+            "description": "Unique identifier of the template"
           },
           "title": {
             "type": "string",
@@ -496,7 +496,7 @@
             "description": "Free-form tags used to categorize the template. Empty array when there are no tags."
           },
           "creator": {
-            "$ref": "#/components/schemas/AgentTemplateCreator"
+            "$ref": "#/components/schemas/TemplateCreator"
           },
           "is_private": {
             "type": "boolean",
@@ -531,7 +531,7 @@
           }
         }
       },
-      "CreateAgentTemplateRequest": {
+      "CreateTemplateRequest": {
         "type": "object",
         "required": [
           "title",
@@ -580,7 +580,7 @@
           }
         }
       },
-      "UpdateAgentTemplateRequest": {
+      "UpdateTemplateRequest": {
         "type": "object",
         "description": "All fields are optional. Only supplied fields are updated.",
         "properties": {
@@ -635,7 +635,7 @@
           }
         }
       },
-      "ListAgentTemplatesResponse": {
+      "ListTemplatesResponse": {
         "type": "object",
         "required": [
           "status",
@@ -652,13 +652,13 @@
           "templates": {
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/AgentTemplate"
+              "$ref": "#/components/schemas/Template"
             },
             "description": "Templates accessible to the authenticated account (own, public, and shared)"
           }
         }
       },
-      "AgentTemplateResponse": {
+      "TemplateResponse": {
         "type": "object",
         "required": [
           "status",
@@ -673,7 +673,7 @@
             "description": "Status of the request"
           },
           "template": {
-            "$ref": "#/components/schemas/AgentTemplate"
+            "$ref": "#/components/schemas/Template"
           }
         }
       },
diff --git a/api-reference/templates/create.mdx b/api-reference/templates/create.mdx
new file mode 100644
index 0000000..19544e6
--- /dev/null
+++ b/api-reference/templates/create.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Create Template'
+openapi: '/api-reference/openapi/templates.json POST /api/templates'
+---
diff --git a/api-reference/templates/delete.mdx b/api-reference/templates/delete.mdx
new file mode 100644
index 0000000..5845898
--- /dev/null
+++ b/api-reference/templates/delete.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Delete Template'
+openapi: '/api-reference/openapi/templates.json DELETE /api/templates/{id}'
+---
diff --git a/api-reference/templates/favorite.mdx b/api-reference/templates/favorite.mdx
new file mode 100644
index 0000000..bb43721
--- /dev/null
+++ b/api-reference/templates/favorite.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Favorite Template'
+openapi: '/api-reference/openapi/templates.json PUT /api/templates/{id}/favorite'
+---
diff --git a/api-reference/templates/list.mdx b/api-reference/templates/list.mdx
new file mode 100644
index 0000000..6003b73
--- /dev/null
+++ b/api-reference/templates/list.mdx
@@ -0,0 +1,4 @@
+---
+title: 'List Templates'
+openapi: '/api-reference/openapi/templates.json GET /api/templates'
+---
diff --git a/api-reference/templates/update.mdx b/api-reference/templates/update.mdx
new file mode 100644
index 0000000..58f73a8
--- /dev/null
+++ b/api-reference/templates/update.mdx
@@ -0,0 +1,4 @@
+---
+title: 'Update Template'
+openapi: '/api-reference/openapi/templates.json PATCH /api/templates/{id}'
+---
diff --git a/docs.json b/docs.json
index 4c1cf94..e430c00 100644
--- a/docs.json
+++ b/docs.json
@@ -245,11 +245,11 @@
           {
             "group": "Templates",
             "pages": [
-              "api-reference/agent-templates/list",
-              "api-reference/agent-templates/create",
-              "api-reference/agent-templates/update",
-              "api-reference/agent-templates/delete",
-              "api-reference/agent-templates/favorite"
+              "api-reference/templates/list",
+              "api-reference/templates/create",
+              "api-reference/templates/update",
+              "api-reference/templates/delete",
+              "api-reference/templates/favorite"
             ]
           },
           {

From 63bcf69e019ae0bf35b561130589eac10b49da0d Mon Sep 17 00:00:00 2001
From: Arpit Gupta <arpitgupta1214@gmail.com>
Date: Tue, 12 May 2026 06:05:53 +0530
Subject: [PATCH 6/7] docs(templates): nest route under /api/agents/templates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 api-reference/openapi/templates.json | 6 +++---
 api-reference/templates/create.mdx   | 2 +-
 api-reference/templates/delete.mdx   | 2 +-
 api-reference/templates/favorite.mdx | 2 +-
 api-reference/templates/list.mdx     | 2 +-
 api-reference/templates/update.mdx   | 2 +-
 6 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/api-reference/openapi/templates.json b/api-reference/openapi/templates.json
index bfb7353..1b76156 100644
--- a/api-reference/openapi/templates.json
+++ b/api-reference/openapi/templates.json
@@ -22,7 +22,7 @@
     }
   ],
   "paths": {
-    "/api/templates": {
+    "/api/agents/templates": {
       "get": {
         "summary": "List templates",
         "description": "Retrieve every template visible to the authenticated account. The response combines templates the account owns, public templates created by other accounts, and private templates that have been shared with the authenticated account's email.",
@@ -133,7 +133,7 @@
         }
       }
     },
-    "/api/templates/{id}": {
+    "/api/agents/templates/{id}": {
       "patch": {
         "summary": "Update a template",
         "description": "Update fields on an existing template owned by the authenticated account. All body fields are optional and only the supplied fields are modified. Providing `share_emails` replaces the existing share list for the template.",
@@ -308,7 +308,7 @@
         }
       }
     },
-    "/api/templates/{id}/favorite": {
+    "/api/agents/templates/{id}/favorite": {
       "put": {
         "summary": "Toggle favorite on a template",
         "description": "Mark or unmark an template as a favorite for the authenticated account. The endpoint is idempotent - calling it repeatedly with the same `is_favourite` value has no additional effect. The caller must be able to see the template (own it, the template is public, or it has been shared with them).",
diff --git a/api-reference/templates/create.mdx b/api-reference/templates/create.mdx
index 19544e6..f140c58 100644
--- a/api-reference/templates/create.mdx
+++ b/api-reference/templates/create.mdx
@@ -1,4 +1,4 @@
 ---
 title: 'Create Template'
-openapi: '/api-reference/openapi/templates.json POST /api/templates'
+openapi: '/api-reference/openapi/templates.json POST /api/agents/templates'
 ---
diff --git a/api-reference/templates/delete.mdx b/api-reference/templates/delete.mdx
index 5845898..f03a39a 100644
--- a/api-reference/templates/delete.mdx
+++ b/api-reference/templates/delete.mdx
@@ -1,4 +1,4 @@
 ---
 title: 'Delete Template'
-openapi: '/api-reference/openapi/templates.json DELETE /api/templates/{id}'
+openapi: '/api-reference/openapi/templates.json DELETE /api/agents/templates/{id}'
 ---
diff --git a/api-reference/templates/favorite.mdx b/api-reference/templates/favorite.mdx
index bb43721..20be00e 100644
--- a/api-reference/templates/favorite.mdx
+++ b/api-reference/templates/favorite.mdx
@@ -1,4 +1,4 @@
 ---
 title: 'Favorite Template'
-openapi: '/api-reference/openapi/templates.json PUT /api/templates/{id}/favorite'
+openapi: '/api-reference/openapi/templates.json PUT /api/agents/templates/{id}/favorite'
 ---
diff --git a/api-reference/templates/list.mdx b/api-reference/templates/list.mdx
index 6003b73..bea110c 100644
--- a/api-reference/templates/list.mdx
+++ b/api-reference/templates/list.mdx
@@ -1,4 +1,4 @@
 ---
 title: 'List Templates'
-openapi: '/api-reference/openapi/templates.json GET /api/templates'
+openapi: '/api-reference/openapi/templates.json GET /api/agents/templates'
 ---
diff --git a/api-reference/templates/update.mdx b/api-reference/templates/update.mdx
index 58f73a8..257050e 100644
--- a/api-reference/templates/update.mdx
+++ b/api-reference/templates/update.mdx
@@ -1,4 +1,4 @@
 ---
 title: 'Update Template'
-openapi: '/api-reference/openapi/templates.json PATCH /api/templates/{id}'
+openapi: '/api-reference/openapi/templates.json PATCH /api/agents/templates/{id}'
 ---

From d9d6820e66f23d45ae1d20de34b4ca838a871df2 Mon Sep 17 00:00:00 2001
From: Arpit Gupta <arpitgupta1214@gmail.com>
Date: Tue, 12 May 2026 06:16:48 +0530
Subject: [PATCH 7/7] docs(templates): replace OpenAPI 3.1-incompatible
 "nullable" with type unions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 api-reference/openapi/templates.json | 12 ++++--------
 1 file changed, 4 insertions(+), 8 deletions(-)

diff --git a/api-reference/openapi/templates.json b/api-reference/openapi/templates.json
index 1b76156..880e91c 100644
--- a/api-reference/openapi/templates.json
+++ b/api-reference/openapi/templates.json
@@ -423,8 +423,7 @@
     },
     "schemas": {
       "TemplateCreator": {
-        "type": "object",
-        "nullable": true,
+        "type": ["object", "null"],
         "description": "The account that created the template. May be null when the creator account is unavailable.",
         "required": [
           "id",
@@ -439,13 +438,11 @@
             "description": "Unique identifier of the creator account"
           },
           "name": {
-            "type": "string",
-            "nullable": true,
+            "type": ["string", "null"],
             "description": "Display name of the creator account"
           },
           "image": {
-            "type": "string",
-            "nullable": true,
+            "type": ["string", "null"],
             "description": "Profile image URL of the creator account"
           },
           "is_admin": {
@@ -524,9 +521,8 @@
             "description": "ISO 8601 timestamp of when the template was created"
           },
           "updated_at": {
-            "type": "string",
+            "type": ["string", "null"],
             "format": "date-time",
-            "nullable": true,
             "description": "ISO 8601 timestamp of when the template was last updated"
           }
         }