From 91a7e54a53c677b93512c193323deff4d2a4e607 Mon Sep 17 00:00:00 2001 From: john Date: Sat, 9 May 2026 21:48:22 +0700 Subject: [PATCH 1/8] docs: add agent templates section and endpoint for listing templates - 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. --- api-reference/agent-templates/list.mdx | 4 + api-reference/openapi/agent-templates.json | 102 +++++++++++++++++++++ api-reference/openapi/research.json | 48 ++++++++++ docs.json | 6 ++ 4 files changed, 160 insertions(+) create mode 100644 api-reference/agent-templates/list.mdx create mode 100644 api-reference/openapi/agent-templates.json diff --git a/api-reference/agent-templates/list.mdx b/api-reference/agent-templates/list.mdx new file mode 100644 index 0000000..15ad109 --- /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/openapi/agent-templates.json b/api-reference/openapi/agent-templates.json new file mode 100644 index 0000000..a9c3930 --- /dev/null +++ b/api-reference/openapi/agent-templates.json @@ -0,0 +1,102 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Recoup API - Agent Templates", + "description": "Agent prompt templates exposed by the Recoup API.", + "license": { + "name": "MIT" + }, + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://api.recoupable.com" + } + ], + "paths": { + "/api/agent-templates": { + "get": { + "description": "Returns agent prompt templates visible to the caller. When `userId` is provided, results include templates the user owns, public templates, and templates shared with that user; each row may include `is_favourite`. When `userId` is omitted, returns public templates only (`is_favourite` is always false). Private templates include `shared_emails` listing addresses the template is shared with.", + "parameters": [ + { + "name": "userId", + "in": "query", + "description": "Optional user id (e.g. authenticated account id) used to scope accessible templates and favorite flags.", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Templates retrieved successfully", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AgentTemplate" + } + } + } + } + }, + "500": { + "description": "Failed to fetch templates", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentTemplatesError" + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "AgentTemplate": { + "type": "object", + "description": "A stored agent template row as returned from the API (shape matches the Chat app response).", + "required": ["id", "title", "description", "prompt", "is_private"], + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "title": { "type": "string" }, + "description": { "type": "string" }, + "prompt": { "type": "string" }, + "tags": { + "type": "array", + "items": { "type": "string" }, + "nullable": true + }, + "creator": { "type": "string", "nullable": true }, + "is_private": { "type": "boolean" }, + "created_at": { "type": "string", "nullable": true }, + "favorites_count": { "type": "integer", "nullable": true }, + "updated_at": { "type": "string", "nullable": true }, + "is_favourite": { + "type": "boolean", + "description": "Present when `userId` was provided; otherwise omitted or false." + }, + "shared_emails": { + "type": "array", + "items": { "type": "string", "format": "email" }, + "description": "For private templates, email addresses the template is shared with; empty array if public or none." + } + } + }, + "AgentTemplatesError": { + "type": "object", + "properties": { + "error": { "type": "string" } + } + } + } + } +} diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index b33d6f4..81ddc23 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -271,6 +271,54 @@ } } }, + "/api/agent-templates": { + "servers": [ + { + "url": "https://chat.recoupable.com" + } + ], + "get": { + "summary": "List agent templates", + "description": "Returns saved prompt templates for agents. Omit `userId` to retrieve public templates only; each item includes `is_favourite: false`. Pass `userId` (same id the Chat app uses for the account, e.g. Privy user id) to include that user's private templates, shared templates, and public templates in one merged list, with `is_favourite` reflecting the user's favorites. Private templates include `shared_emails` for addresses the template is shared with.", + "security": [], + "parameters": [ + { + "name": "userId", + "in": "query", + "description": "Optional. When omitted, only public templates are returned.", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Templates retrieved successfully", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AgentTemplate" + } + } + } + } + }, + "500": { + "description": "Failed to fetch templates", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentTemplatesErrorResponse" + } + } + } + } + } + } + }, "/api/chats/{id}/artist": { "get": { "description": "Retrieve the artist associated with a specific chat room. Returns 404 if the chat does not exist or is not accessible by the authenticated caller.", diff --git a/docs.json b/docs.json index fdf0a2c..c1fa138 100644 --- a/docs.json +++ b/docs.json @@ -235,6 +235,12 @@ "api-reference/agents/verify" ] }, + { + "group": "Agent templates", + "pages": [ + "api-reference/agent-templates/list" + ] + }, { "group": "Agents", "pages": [ From 85d166f3b375db715f187d23cda9775e64324c40 Mon Sep 17 00:00:00 2001 From: john Date: Sat, 9 May 2026 22:00:52 +0700 Subject: [PATCH 2/8] docs(openapi): update agent templates endpoint and security specifications - 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. --- api-reference/openapi/agent-templates.json | 44 ++++++++++++++++------ 1 file changed, 32 insertions(+), 12 deletions(-) diff --git a/api-reference/openapi/agent-templates.json b/api-reference/openapi/agent-templates.json index a9c3930..4534ddb 100644 --- a/api-reference/openapi/agent-templates.json +++ b/api-reference/openapi/agent-templates.json @@ -16,16 +16,14 @@ "paths": { "/api/agent-templates": { "get": { - "description": "Returns agent prompt templates visible to the caller. When `userId` is provided, results include templates the user owns, public templates, and templates shared with that user; each row may include `is_favourite`. When `userId` is omitted, returns public templates only (`is_favourite` is always false). Private templates include `shared_emails` listing addresses the template is shared with.", - "parameters": [ + "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. Private templates include `shared_emails` when applicable.", + "parameters": [], + "security": [ { - "name": "userId", - "in": "query", - "description": "Optional user id (e.g. authenticated account id) used to scope accessible templates and favorite flags.", - "required": false, - "schema": { - "type": "string" - } + "apiKeyAuth": [] + }, + { + "bearerAuth": [] } ], "responses": { @@ -42,6 +40,16 @@ } } }, + "401": { + "description": "Missing or invalid credentials", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentTemplatesError" + } + } + } + }, "500": { "description": "Failed to fetch templates", "content": { @@ -57,10 +65,22 @@ } }, "components": { + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer" + }, + "apiKeyAuth": { + "type": "apiKey", + "in": "header", + "name": "x-api-key", + "description": "Your Recoup API key. [Learn more](/quickstart#api-keys)." + } + }, "schemas": { "AgentTemplate": { "type": "object", - "description": "A stored agent template row as returned from the API (shape matches the Chat app response).", + "description": "A stored agent template row as returned from the API.", "required": ["id", "title", "description", "prompt", "is_private"], "properties": { "id": { @@ -82,12 +102,12 @@ "updated_at": { "type": "string", "nullable": true }, "is_favourite": { "type": "boolean", - "description": "Present when `userId` was provided; otherwise omitted or false." + "description": "Whether this template is a favorite for the authenticated caller." }, "shared_emails": { "type": "array", "items": { "type": "string", "format": "email" }, - "description": "For private templates, email addresses the template is shared with; empty array if public or none." + "description": "For private templates the caller owns or can access, email addresses the template is shared with; otherwise empty array." } } }, From 1a77ec5699877586319c05c3eb65d24e734197af Mon Sep 17 00:00:00 2001 From: john Date: Sat, 9 May 2026 22:14:23 +0700 Subject: [PATCH 3/8] docs(openapi): simplify agent templates endpoint reference - 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. --- api-reference/agent-templates/list.mdx | 2 +- api-reference/openapi/research.json | 48 -------------------------- 2 files changed, 1 insertion(+), 49 deletions(-) diff --git a/api-reference/agent-templates/list.mdx b/api-reference/agent-templates/list.mdx index 15ad109..e3fb249 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: 'GET /api/agent-templates' --- diff --git a/api-reference/openapi/research.json b/api-reference/openapi/research.json index 81ddc23..b33d6f4 100644 --- a/api-reference/openapi/research.json +++ b/api-reference/openapi/research.json @@ -271,54 +271,6 @@ } } }, - "/api/agent-templates": { - "servers": [ - { - "url": "https://chat.recoupable.com" - } - ], - "get": { - "summary": "List agent templates", - "description": "Returns saved prompt templates for agents. Omit `userId` to retrieve public templates only; each item includes `is_favourite: false`. Pass `userId` (same id the Chat app uses for the account, e.g. Privy user id) to include that user's private templates, shared templates, and public templates in one merged list, with `is_favourite` reflecting the user's favorites. Private templates include `shared_emails` for addresses the template is shared with.", - "security": [], - "parameters": [ - { - "name": "userId", - "in": "query", - "description": "Optional. When omitted, only public templates are returned.", - "required": false, - "schema": { - "type": "string" - } - } - ], - "responses": { - "200": { - "description": "Templates retrieved successfully", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AgentTemplate" - } - } - } - } - }, - "500": { - "description": "Failed to fetch templates", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AgentTemplatesErrorResponse" - } - } - } - } - } - } - }, "/api/chats/{id}/artist": { "get": { "description": "Retrieve the artist associated with a specific chat room. Returns 404 if the chat does not exist or is not accessible by the authenticated caller.", From 5ec5afd69148e8c20008744021762e25f7268bb8 Mon Sep 17 00:00:00 2001 From: john Date: Sat, 9 May 2026 22:20:50 +0700 Subject: [PATCH 4/8] docs(openapi): clarify agent templates endpoint description - 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. --- api-reference/openapi/agent-templates.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/openapi/agent-templates.json b/api-reference/openapi/agent-templates.json index 4534ddb..463065f 100644 --- a/api-reference/openapi/agent-templates.json +++ b/api-reference/openapi/agent-templates.json @@ -2,7 +2,7 @@ "openapi": "3.1.0", "info": { "title": "Recoup API - Agent Templates", - "description": "Agent prompt templates exposed by the Recoup API.", + "description": "Lists agent prompt templates (`GET /api/agent-templates`). This operation is documented only here; clients call the Recoup API base URL in `servers` below.", "license": { "name": "MIT" }, From aaf62f9fb70aec1430c8da942e3f673841635701 Mon Sep 17 00:00:00 2001 From: john Date: Sat, 9 May 2026 22:28:23 +0700 Subject: [PATCH 5/8] docs(openapi): update agent templates schema to include 'is_favourite' - 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. --- api-reference/openapi/agent-templates.json | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/api-reference/openapi/agent-templates.json b/api-reference/openapi/agent-templates.json index 463065f..3c961ac 100644 --- a/api-reference/openapi/agent-templates.json +++ b/api-reference/openapi/agent-templates.json @@ -2,7 +2,7 @@ "openapi": "3.1.0", "info": { "title": "Recoup API - Agent Templates", - "description": "Lists agent prompt templates (`GET /api/agent-templates`). This operation is documented only here; clients call the Recoup API base URL in `servers` below.", + "description": "Lists agent prompt templates (`GET /api/agent-templates`). Clients use the Recoup API base URL from `servers`.", "license": { "name": "MIT" }, @@ -81,7 +81,14 @@ "AgentTemplate": { "type": "object", "description": "A stored agent template row as returned from the API.", - "required": ["id", "title", "description", "prompt", "is_private"], + "required": [ + "id", + "title", + "description", + "prompt", + "is_private", + "is_favourite" + ], "properties": { "id": { "type": "string", From ae3ac5e59795e463a502bfe48c380bac279e8afd Mon Sep 17 00:00:00 2001 From: john Date: Sun, 10 May 2026 02:15:34 +0700 Subject: [PATCH 6/8] docs(openapi): refine agent templates endpoint descriptions - 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. --- api-reference/openapi/agent-templates.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-reference/openapi/agent-templates.json b/api-reference/openapi/agent-templates.json index 3c961ac..85737a3 100644 --- a/api-reference/openapi/agent-templates.json +++ b/api-reference/openapi/agent-templates.json @@ -16,7 +16,7 @@ "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. Private templates include `shared_emails` when applicable.", + "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.", "parameters": [], "security": [ { @@ -114,7 +114,7 @@ "shared_emails": { "type": "array", "items": { "type": "string", "format": "email" }, - "description": "For private templates the caller owns or can access, email addresses the template is shared with; otherwise empty array." + "description": "Email addresses for accounts the template is shared with — only populated for **private templates owned by** the authenticated caller; otherwise empty array." } } }, From 4b1060c635d761a8e3b760be4ff1bd1807a1a437 Mon Sep 17 00:00:00 2001 From: john Date: Tue, 12 May 2026 22:26:40 +0700 Subject: [PATCH 7/8] docs: update navigation and endpoint references for agent templates - 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. --- api-reference/agent-templates/list.mdx | 2 +- api-reference/openapi/agent-templates.json | 4 ++-- docs.json | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/api-reference/agent-templates/list.mdx b/api-reference/agent-templates/list.mdx index e3fb249..bd6186d 100644 --- a/api-reference/agent-templates/list.mdx +++ b/api-reference/agent-templates/list.mdx @@ -1,4 +1,4 @@ --- title: List Agent Templates -openapi: 'GET /api/agent-templates' +openapi: '/api-reference/openapi/agent-templates.json GET /api/agents/templates' --- diff --git a/api-reference/openapi/agent-templates.json b/api-reference/openapi/agent-templates.json index 85737a3..f101522 100644 --- a/api-reference/openapi/agent-templates.json +++ b/api-reference/openapi/agent-templates.json @@ -2,7 +2,7 @@ "openapi": "3.1.0", "info": { "title": "Recoup API - Agent Templates", - "description": "Lists agent prompt templates (`GET /api/agent-templates`). Clients use the Recoup API base URL from `servers`.", + "description": "Lists agent prompt templates (`GET /api/agents/templates`). Clients use the Recoup API base URL from `servers`.", "license": { "name": "MIT" }, @@ -14,7 +14,7 @@ } ], "paths": { - "/api/agent-templates": { + "/api/agents/templates": { "get": { "description": "Returns agent prompt templates visible to the **authenticated** caller. The account is resolved from `Authorization: Bearer` or `x-api-key` — 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.", "parameters": [], diff --git a/docs.json b/docs.json index c1fa138..d574265 100644 --- a/docs.json +++ b/docs.json @@ -229,14 +229,14 @@ "tab": "Agents & Sandboxes", "groups": [ { - "group": "Agent Onboarding", + "group": "Workflows", "pages": [ "api-reference/agents/signup", "api-reference/agents/verify" ] }, { - "group": "Agent templates", + "group": "Templates", "pages": [ "api-reference/agent-templates/list" ] From 9bb90989008006b4bc843b9d83d3f44bae8a57b4 Mon Sep 17 00:00:00 2001 From: john Date: Tue, 12 May 2026 22:44:09 +0700 Subject: [PATCH 8/8] docs(openapi): refine agent templates endpoint description - Updated the description for the `/api/agents/templates` endpoint to remove redundant phrasing, enhancing clarity and readability for users accessing the API. --- api-reference/openapi/agent-templates.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/openapi/agent-templates.json b/api-reference/openapi/agent-templates.json index f101522..7050f44 100644 --- a/api-reference/openapi/agent-templates.json +++ b/api-reference/openapi/agent-templates.json @@ -16,7 +16,7 @@ "paths": { "/api/agents/templates": { "get": { - "description": "Returns agent prompt templates visible to the **authenticated** caller. The account is resolved from `Authorization: Bearer` or `x-api-key` — 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.", "parameters": [], "security": [ {