---
title: "Create Eval"
method: POST
path: "/v2/evals"
tags: ["Evals"]
---

# Create Eval

`POST /v2/evals`

Create a new eval using an eval type configuration.

Args:
    eval_request (Eval): Data for the eval to create, including eval type and configuration.

Returns:
    Eval: The created eval object.

Raises:
    AymaraAPIError: If the request is invalid.

Example:
    POST /api/evals
    {
        "eval_type": "...",
        "workspace_uuid": "...",
        ...
    }

## Request body

- Eval — Schema for configuring an Eval based on a eval_type.
  - `eval_uuid` string, nullable — Unique identifier for the evaluation.
  - `name` string, nullable — Name of the evaluation.
  - `created_by` string, nullable — Name of the user who created the evaluation.
  - `ai_description` string, required — Description of the AI under evaluation.
  - `ai_instructions` union — Instructions the AI should follow. String for normal evals, AgentInstructions for single-agent evals, WorkflowInstructions for multi-agent workflows.
    - string
    - AgentInstructions
      - `agent_name` string, nullable
      - `system_prompt` string, required
      - `tools` union — Instructions for the agent, can be a string or a list/dict of tools.
        - ToolArray — Container for an array of tools
          - `type` 'array'
          - `value` Tool[], required
            - `name` string, required
            - `content` union, required
              - …
        - ToolDict — Container for a tool dictionary
          - `type` 'dict'
          - `value` object, required
        - ToolString — Container for string-based tool instructions
          - `type` 'string'
          - `value` string, required
    - WorkflowInstructions — Workflow instructions for multi-agent workflows.
      - `instructions` AgentInstructions[], required — List of agent instructions for the workflow. Must contain at least one agent.
        - `agent_name` string, nullable
        - `system_prompt` string, required
        - `tools` union — Instructions for the agent, can be a string or a list/dict of tools.
          - ToolArray — Container for an array of tools
            - `type` 'array'
            - `value` Tool[], required
              - …
          - ToolDict — Container for a tool dictionary
            - `type` 'dict'
            - `value` object, required
          - ToolString — Container for string-based tool instructions
            - `type` 'string'
            - `value` string, required
  - `eval_type` string, required — Type of the eval (safety, accuracy, etc.)
  - `eval_instructions` string, nullable — Additional instructions for the eval, if any.
  - `language` string, nullable — Language code for the eval (default: "en").
  - `modality` 'text' | 'image' | 'video' — Content type for AI interactions.
  - `ground_truth` union — Ground truth data or reference file, if any.
    - string
    - FileReference — Reference to a file, either by file_uuid (preferred) or legacy remote_file_path. When file_uuid is provided, the system will look up the File record and use its remote_file_path. The remote_file_path field is maintained for backwards compatibility.
      - `file_uuid` string, nullable
      - `remote_file_path` string, nullable
  - `num_prompts` integer, nullable — Number of prompts/questions in the eval (default: 50).
  - `prompt_examples` PromptExample[], nullable — List of example prompts for the eval.
    - `content` string, required — Content of the example prompt.
    - `example_uuid` string, nullable — Unique identifier for the example, if any.
    - `type` 'good' | 'bad'
    - `explanation` string, nullable — Explanation for the example, if any.
  - `is_jailbreak` boolean — Indicates if the eval is a jailbreak test.
  - `is_sandbox` boolean — Indicates if the eval results are sandboxed.
  - `workspace_uuid` string, nullable — UUID of the associated workspace, if any.
  - `status` 'created' | 'processing' | 'finished' | 'failed' — Resource status.
  - `created_at` string, date-time, nullable — Timestamp when the eval was created.
  - `updated_at` string, date-time, nullable — Timestamp when the eval was last updated.

## Response `201`

Created

- Eval — Schema for configuring an Eval based on a eval_type.
  - `eval_uuid` string, nullable — Unique identifier for the evaluation.
  - `name` string, nullable — Name of the evaluation.
  - `created_by` string, nullable — Name of the user who created the evaluation.
  - `ai_description` string, required — Description of the AI under evaluation.
  - `ai_instructions` union — Instructions the AI should follow. String for normal evals, AgentInstructions for single-agent evals, WorkflowInstructions for multi-agent workflows.
    - string
    - AgentInstructions
      - `agent_name` string, nullable
      - `system_prompt` string, required
      - `tools` union — Instructions for the agent, can be a string or a list/dict of tools.
        - ToolArray — Container for an array of tools
          - `type` 'array'
          - `value` Tool[], required
            - `name` string, required
            - `content` union, required
              - …
        - ToolDict — Container for a tool dictionary
          - `type` 'dict'
          - `value` object, required
        - ToolString — Container for string-based tool instructions
          - `type` 'string'
          - `value` string, required
    - WorkflowInstructions — Workflow instructions for multi-agent workflows.
      - `instructions` AgentInstructions[], required — List of agent instructions for the workflow. Must contain at least one agent.
        - `agent_name` string, nullable
        - `system_prompt` string, required
        - `tools` union — Instructions for the agent, can be a string or a list/dict of tools.
          - ToolArray — Container for an array of tools
            - `type` 'array'
            - `value` Tool[], required
              - …
          - ToolDict — Container for a tool dictionary
            - `type` 'dict'
            - `value` object, required
          - ToolString — Container for string-based tool instructions
            - `type` 'string'
            - `value` string, required
  - `eval_type` string, required — Type of the eval (safety, accuracy, etc.)
  - `eval_instructions` string, nullable — Additional instructions for the eval, if any.
  - `language` string, nullable — Language code for the eval (default: "en").
  - `modality` 'text' | 'image' | 'video' — Content type for AI interactions.
  - `ground_truth` union — Ground truth data or reference file, if any.
    - string
    - FileReference — Reference to a file, either by file_uuid (preferred) or legacy remote_file_path. When file_uuid is provided, the system will look up the File record and use its remote_file_path. The remote_file_path field is maintained for backwards compatibility.
      - `file_uuid` string, nullable
      - `remote_file_path` string, nullable
  - `num_prompts` integer, nullable — Number of prompts/questions in the eval (default: 50).
  - `prompt_examples` PromptExample[], nullable — List of example prompts for the eval.
    - `content` string, required — Content of the example prompt.
    - `example_uuid` string, nullable — Unique identifier for the example, if any.
    - `type` 'good' | 'bad'
    - `explanation` string, nullable — Explanation for the example, if any.
  - `is_jailbreak` boolean — Indicates if the eval is a jailbreak test.
  - `is_sandbox` boolean — Indicates if the eval results are sandboxed.
  - `workspace_uuid` string, nullable — UUID of the associated workspace, if any.
  - `status` 'created' | 'processing' | 'finished' | 'failed' — Resource status.
  - `created_at` string, date-time, nullable — Timestamp when the eval was created.
  - `updated_at` string, date-time, nullable — Timestamp when the eval was last updated.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `422` — Unprocessable Entity
- `429` — Too Many Requests
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.net/aymara-ai/apis/aymara-api.md) · [All operations](https://skmtc.net/aymara-ai/apis/aymara-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aymara-ai/aymara-api/versions/0cb64ef11adf/schema)