RecoupGet a Free AuditFree Audit

API REFERENCE

Create Template

On this page
POST/api/agents/templates

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.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL
curl --request POST \
  --url 'https://api.recoupable.dev/api/agents/templates' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "string",
  "description": "string",
  "prompt": "string",
  "tags": [
    "string"
  ],
  "is_private": true
}'

Request body required

Template fields

application/json

titlestringrequired

Short human-readable title for the template

minLength: 3 · maxLength: 50

descriptionstringrequired

Description of what the template does

minLength: 10 · maxLength: 200

promptstringrequired

The agent prompt body

minLength: 20 · maxLength: 10000

tagsarray<string>required

Free-form tags used to categorize the template. Pass an empty array if there are no tags.

Item properties for tags

string

is_privatebooleanrequired

When true, the template is restricted to the creator and the accounts listed in share_emails

share_emailsarray<string>

Emails to grant access to. Only applied when is_private is true. Defaults to an empty array when omitted.

Item properties for share_emails

string

Responses

201Template created successfully

application/json

statusstring · enumrequired

Status of the request

Values: "success"

templateobjectrequired
Properties for template
idstringrequired

Unique identifier of the template

format: uuid

titlestringrequired

Short human-readable title for the template (3-50 characters)

descriptionstringrequired

Description of what the template does (10-200 characters)

promptstringrequired

The agent prompt body (20-10000 characters)

tagsarray<string>required

Free-form tags used to categorize the template. Empty array when there are no tags.

Item properties for tags

string

creatorobject | nullrequired

The account that created the template. May be null when the creator account is unavailable.

Properties for creator
idstringrequired

Unique identifier of the creator account

format: uuid

namestring | nullrequired

Display name of the creator account

imagestring | nullrequired

Profile image URL of the creator account

is_adminbooleanrequired

Whether the creator is a Recoup admin (their account email is on the platform admin allow-list)

is_privatebooleanrequired

Whether the template is restricted to the creator and explicitly shared accounts

is_favouritebooleanrequired

Whether the authenticated account has favorited this template

favorites_countintegerrequired

Total number of accounts that have favorited this template

shared_emailsarray<string>required

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.

Item properties for shared_emails

string

created_atstringrequired

ISO 8601 timestamp of when the template was created

format: date-time

updated_atstring | nullrequired

ISO 8601 timestamp of when the template was last updated

format: date-time

400Bad request - validation failed or required fields missing

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Human-readable error message

missing_fieldsarray<string>

Names of required fields that were missing from the request, when applicable

Item properties for missing_fields

string

401Unauthorized - missing or invalid credentials

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Human-readable error message

missing_fieldsarray<string>

Names of required fields that were missing from the request, when applicable

Item properties for missing_fields

string

500Internal server error

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Human-readable error message

missing_fieldsarray<string>

Names of required fields that were missing from the request, when applicable

Item properties for missing_fields

string

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download templates.json
View operation source
json
{
  "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": []
    },
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "description": "Template fields",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateTemplateRequest"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Template created successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TemplateResponse"
          }
        }
      }
    },
    "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"
          }
        }
      }
    }
  }
}