# List Templates

Source: https://recoupable.dev/docs/api-reference/templates/list

List templates

## GET /api/agents/templates

Full OpenAPI specification: https://recoupable.dev/docs/spec/templates.json

## Authentication

This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "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"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/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.",
        "security": [
          {
            "apiKeyAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Templates retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListTemplatesResponse"
                }
              }
            }
          },
          "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": {
    "schemas": {
      "ListTemplatesResponse": {
        "type": "object",
        "required": [
          "status",
          "templates"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "success"
            ],
            "description": "Status of the request"
          },
          "templates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Template"
            },
            "description": "Templates accessible to the authenticated account (own, public, and shared)"
          }
        }
      },
      "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"
          }
        }
      },
      "Template": {
        "type": "object",
        "required": [
          "id",
          "title",
          "description",
          "prompt",
          "tags",
          "creator",
          "is_private",
          "is_favourite",
          "favorites_count",
          "shared_emails",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the 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",
            "items": {
              "type": "string"
            },
            "description": "Free-form tags used to categorize the template. Empty array when there are no tags."
          },
          "creator": {
            "$ref": "#/components/schemas/TemplateCreator"
          },
          "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",
            "description": "Total number of accounts that have favorited this template"
          },
          "shared_emails": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            },
            "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",
            "description": "ISO 8601 timestamp of when the template was created"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "ISO 8601 timestamp of when the template was last updated"
          }
        }
      },
      "TemplateCreator": {
        "type": [
          "object",
          "null"
        ],
        "description": "The account that created the template. May be null when the creator account is unavailable.",
        "required": [
          "id",
          "name",
          "image",
          "is_admin"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the creator account"
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Display name of the creator account"
          },
          "image": {
            "type": [
              "string",
              "null"
            ],
            "description": "Profile image URL of the creator account"
          },
          "is_admin": {
            "type": "boolean",
            "description": "Whether the creator is a Recoup admin (their account email is on the platform admin allow-list)"
          }
        }
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your Recoup API key. [Learn more](/quickstart#api-keys)."
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```