> ## Documentation Index > Fetch the complete documentation index at: https://docs.coval.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a template > Create a new simulation configuration template. ## OpenAPI ````yaml /api-reference/v1/templates-v1.yaml post /v1/templates openapi: 3.0.3 info: title: Coval Templates API version: 1.0.0 description: | Manage reusable simulation configuration templates for evaluations. contact: name: Coval API Support email: support@coval.dev url: https://docs.coval.dev license: name: Proprietary url: https://coval.dev/terms servers: - url: https://api.coval.dev description: Production API security: - ApiKeyAuth: [] tags: - name: Templates description: CRUD operations for simulation configuration templates paths: /v1/templates: post: tags: - Templates summary: Create a template description: Create a new simulation configuration template. operationId: createTemplate requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTemplateRequest' examples: voiceTemplate: $ref: '#/components/examples/CreateVoiceTemplate' minimalTemplate: $ref: '#/components/examples/CreateMinimalTemplate' responses: '201': description: Template created successfully content: application/json: schema: $ref: '#/components/schemas/CreateTemplateResponse' examples: created: $ref: '#/components/examples/TemplateCreated' '400': description: Invalid request body or validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingField: $ref: '#/components/examples/MissingFieldError' invalidAgentId: $ref: '#/components/examples/InvalidAgentIdError' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] components: schemas: CreateTemplateRequest: type: object required: - name - simulation_type - agent_id properties: name: type: string description: Human-readable template name minLength: 1 maxLength: 200 example: Customer Support Voice Template description: type: string nullable: true description: Template description maxLength: 1000 example: Standard voice simulation template for customer support scenarios simulation_type: $ref: '#/components/schemas/SimulationType' simulation_metadata: type: object description: Simulation-specific configuration (JSONB) additionalProperties: true default: {} example: greeting: Hello, how can I help you? simulated_user_prompt: type: string nullable: true description: Instructions for the simulated customer behavior example: You are a customer calling about a delayed food delivery... agent_id: type: string description: Associated agent ID pattern: ^[A-Za-z0-9]{22}$ example: 3zfmuDbVQsi4GaseDtiVcS enabled_metrics: type: array description: List of metric IDs to evaluate items: type: string default: [] example: - metric_abc123 persona_ids: type: array nullable: true description: List of persona IDs for customer simulation items: type: string example: - persona_xyz789 test_set_id: type: string nullable: true description: Associated test set ID example: testset_abc123 iteration_count: type: integer description: Number of simulation iterations to run minimum: 1 maximum: 10000 default: 1 example: 10 concurrency: type: integer description: Number of parallel simulations to run minimum: 1 maximum: 100 default: 1 example: 5 sub_sample_size: type: integer nullable: true description: Maximum number of test cases to sample from test set minimum: 1 example: 50 test_case_params_by_iteration: type: array description: Per-iteration parameter overrides items: type: object additionalProperties: true default: [] example: [] CreateTemplateResponse: type: object required: - template properties: template: $ref: '#/components/schemas/TemplateResource' ErrorResponse: type: object description: Standard error response required: - error properties: error: type: object required: - code - message - details properties: code: type: string description: Error code enum enum: - INVALID_ARGUMENT - UNAUTHENTICATED - NOT_FOUND - ALREADY_EXISTS - INTERNAL example: INVALID_ARGUMENT message: type: string description: Human-readable error message example: Invalid request parameter details: type: array description: Detailed error information items: type: object properties: field: type: string nullable: true description: Field name that caused the error example: agent_id description: type: string description: Detailed error description example: Agent not found or not accessible SimulationType: type: string description: Type of simulation (matches SimulatorType enum from agents API) enum: - SIMULATOR_VOICE - SIMULATOR_OUTBOUND_VOICE - SIMULATOR_SMS - SIMULATOR_CHAT - SIMULATOR_WEBSOCKET - SIMULATOR_LIVEKIT - SIMULATOR_OPENAI_REALTIME - SIMULATOR_OPENAI_ENDPOINT - SIMULATOR_TTS - SIMULATOR_TRANSCRIPTION - SIMULATOR_VOICE_TO_VOICE - SIMULATOR_NOOP example: SIMULATOR_VOICE TemplateResource: type: object description: > Template configuration resource for reusable simulation setups. Templates define complete simulation configurations including agent references, customer prompts, metrics, personas, and execution parameters. properties: id: type: string description: Template resource ID pattern: ^[A-Za-z0-9]{22}$ example: abc123def456ghi789jklm name: type: string description: Resource name (templates/{id}) pattern: ^templates/[A-Za-z0-9]{22}$ example: templates/abc123def456ghi789jklm template_name: type: string description: Human-readable template name minLength: 1 maxLength: 200 example: Customer Support Voice Template description: type: string nullable: true description: Template description maxLength: 1000 example: Standard voice simulation template for customer support scenarios simulation_type: $ref: '#/components/schemas/SimulationType' simulation_metadata: type: object description: Simulation-specific configuration (JSONB) additionalProperties: true example: greeting: Hello, how can I help you? max_duration_seconds: 300 simulated_user_prompt: type: string nullable: true description: Instructions for the simulated customer behavior example: You are a customer calling about a delayed food delivery... agent_id: type: string description: Associated agent ID pattern: ^[A-Za-z0-9]{22}$ example: 3zfmuDbVQsi4GaseDtiVcS enabled_metrics: type: array description: List of metric IDs to evaluate items: type: string default: [] example: - metric_abc123 - metric_def456 persona_ids: type: array nullable: true description: List of persona IDs for customer simulation items: type: string example: - persona_xyz789 test_set_id: type: string nullable: true description: Associated test set ID example: testset_abc123 iteration_count: type: integer description: Number of simulation iterations to run minimum: 1 maximum: 10000 default: 1 example: 10 concurrency: type: integer description: Number of parallel simulations to run minimum: 1 maximum: 100 default: 1 example: 5 sub_sample_size: type: integer nullable: true description: Maximum number of test cases to sample from test set minimum: 1 example: 50 test_case_params_by_iteration: type: array description: Per-iteration parameter overrides (JSONB array) items: type: object additionalProperties: true default: [] example: - iteration: 1 params: custom_field: value1 - iteration: 2 params: custom_field: value2 create_time: type: string format: date-time description: Creation timestamp (ISO 8601) example: '2025-10-14T12:00:00Z' update_time: type: string format: date-time nullable: true description: Last update timestamp (ISO 8601) example: '2025-10-15T14:30:00Z' examples: CreateVoiceTemplate: summary: Create voice simulation template value: name: Customer Support Voice Template description: Standard voice simulation template for support calls simulation_type: SIMULATOR_VOICE simulation_metadata: greeting: Hello, how can I help you? simulated_user_prompt: You are a customer calling about a delayed delivery... agent_id: 3zfmuDbVQsi4GaseDtiVcS enabled_metrics: - metric_abc123 persona_ids: - persona_xyz789 iteration_count: 10 concurrency: 5 CreateMinimalTemplate: summary: Create minimal template (required fields only) value: name: Minimal Template simulation_type: SIMULATOR_CHAT agent_id: 3zfmuDbVQsi4GaseDtiVcS TemplateCreated: summary: Template created successfully value: template: id: new123def456ghi789jklm name: templates/new123def456ghi789jklm template_name: Customer Support Voice Template description: Standard voice simulation template for support calls simulation_type: SIMULATOR_VOICE simulation_metadata: greeting: Hello, how can I help you? simulated_user_prompt: You are a customer calling about a delayed delivery... agent_id: 3zfmuDbVQsi4GaseDtiVcS enabled_metrics: - metric_abc123 persona_ids: - persona_xyz789 test_set_id: null iteration_count: 10 concurrency: 5 sub_sample_size: null test_case_params_by_iteration: [] create_time: '2025-11-03T12:00:00Z' update_time: null MissingFieldError: summary: Missing required field value: error: code: INVALID_ARGUMENT message: Invalid request body details: - description: |- 1 validation error for CreateTemplateRequest name Field required [type=missing] InvalidAgentIdError: summary: Invalid or non-existent agent_id value: error: code: INVALID_ARGUMENT message: Invalid agent_id details: - field: agent_id description: Agent not found or not accessible by your organization responses: Unauthorized: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UNAUTHENTICATED message: Authentication failed details: - field: X-API-Key description: Invalid or missing API key InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INTERNAL message: Internal server error details: - description: An unexpected error occurred securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication ````