> ## 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. # List templates > Retrieve a paginated list of simulation templates with optional filtering and sorting. ## OpenAPI ````yaml /api-reference/v1/templates-v1.yaml get /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: get: tags: - Templates summary: List templates description: >- Retrieve a paginated list of simulation templates with optional filtering and sorting. operationId: listTemplates parameters: - name: filter in: query required: false schema: type: string description: > **Supported fields:** `simulation_type`, `template_name`, `agent_id`, `create_time`, `update_time` **Operators:** `=`, `!=`, `>`, `<`, `>=`, `<=`, `AND`, `OR` **Date format:** ISO 8601 (e.g., `2025-10-01T00:00:00Z`) examples: bySimulationType: value: simulation_type="SIMULATOR_VOICE" summary: Filter by simulation type byAgentId: value: agent_id="abc123def456ghi789jklm" summary: Filter by agent combined: value: >- simulation_type="SIMULATOR_VOICE" AND create_time>="2025-10-01T00:00:00Z" summary: Combined filters - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 50 description: Maximum number of results per page example: 50 - name: page_token in: query required: false schema: type: string description: | Opaque pagination token from previous response. Do not decode or modify this token. example: eyJvZmZzZXQiOjUwfQ== - name: order_by in: query required: false schema: type: string default: '-create_time' description: > Sort order specification. **Formats:** 1. Dash-prefix: `-create_time` (descending), `template_name` (ascending) 2. Space-separated: `create_time desc`, `template_name asc` **Sortable fields:** `create_time`, `update_time`, `template_name`, `simulation_type` examples: descending: value: '-create_time' summary: Newest first (default) ascending: value: template_name summary: Alphabetical by name spaceSeparated: value: create_time desc summary: Space-separated format responses: '200': description: Templates retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ListTemplatesResponse' examples: success: $ref: '#/components/examples/ListTemplatesSuccess' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidFilter: $ref: '#/components/examples/InvalidFilterError' invalidPageSize: $ref: '#/components/examples/InvalidPageSizeError' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] components: schemas: ListTemplatesResponse: type: object required: - templates properties: templates: type: array description: List of template resources items: $ref: '#/components/schemas/TemplateResource' next_page_token: type: string nullable: true description: Token for fetching next page (null if no more results) example: eyJvZmZzZXQiOjUwfQ== 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 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' 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 examples: ListTemplatesSuccess: summary: Successful list response value: templates: - id: abc123def456ghi789jklm name: templates/abc123def456ghi789jklm template_name: Customer Support Voice Template description: Standard voice simulation template 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-10-14T12:00:00Z' update_time: '2025-10-15T14:30:00Z' next_page_token: eyJvZmZzZXQiOjUwfQ== InvalidFilterError: summary: Invalid filter expression value: error: code: INVALID_ARGUMENT message: Invalid filter expression details: - field: filter description: >- Unknown field 'invalid_field'. Valid fields: simulation_type, template_name, agent_id, create_time, update_time InvalidPageSizeError: summary: Invalid page size value: error: code: INVALID_ARGUMENT message: Invalid page_size details: - field: page_size description: page_size must be between 1 and 100 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 ````