---
title: "Freeze the draft as a revision and test it"
method: POST
path: "/v3/ai-agents/{agent_id}/revisions"
tags: ["v3", "ai-agents"]
---

# Freeze the draft as a revision and test it

`POST /v3/ai-agents/{agent_id}/revisions`

## Request

- Base URL: `https://api.mentium.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mentium.io/v3/ai-agents/{agent_id}/revisions`
- Auth: HTTP bearer

Creates the next revision from the saved draft and starts its tests; publish it once they pass.

## Path parameters

- `agent_id` string, uuid, required

## Headers

- `mentium-workspace-id` string, nullable

## Request body

- AgentRevisionCreateRequest
  - `evaluate` boolean: Run the agent's tests on it; without them it can only be published with an override reason

## Response `202`

Successful Response

- AgentRevisionResponse
  - `id` string, required
  - `agent_id` string, required
  - `revision_number` integer, required
  - `status` 'candidate' | 'evaluated' | 'published', required
  - `is_live` boolean: The agent runs this revision now
  - `config` AgentRevisionConfig, required: Every field that changes how the agent behaves; name, activation and phone number are not behavior.
    - `agent_type` string, required
    - `model` string, required
    - `temperature` number, nullable
    - `max_tokens` integer, nullable
    - `reasoning_effort` string, nullable
    - `system_prompt_template` string, required
    - `user_prompt_template` string, nullable
    - `tools` string[]
    - `tool_inputs` object, nullable
    - `type_config` object
    - `automation_tool_bindings` AgentRevisionAutomationToolBinding[]
      - `automation_tool_id` string, required
      - `allowed_tool_names` string[]
      - `configuration_overrides` object, nullable
    - `mcp_bindings` AgentRevisionMcpBinding[]
      - `integration_connection_id` string, required
      - `allowed_tool_names` string[]
  - `config_digest` string, required
  - `platform_contract_digest` string, nullable
  - `suite_digest` string, nullable
  - `gate_passed` boolean, nullable: Every applicable Mentium safety check passed; null until evaluated, and for revisions never tested
  - `gate_override_reason` string, nullable
  - `message` string, nullable: What the version changes, written when it was first published
  - `gate_overridden_by_email` string, nullable
  - `created_by_email` string, nullable
  - `published_by_email` string, nullable
  - `based_on_revision_number` integer, nullable: The version that was live when this one was frozen: the version it was changed from
  - `created_by_impersonator_email` string, nullable: The admin acting as the user who created it
  - `published_by_impersonator_email` string, nullable: The admin acting as the user who published it
  - `gate_overridden_by_impersonator_email` string, nullable: The admin acting as the user who overrode the gate
  - `tests` AgentRevisionTestSummary
    - `total` integer
    - `passed` integer
    - `failed` integer
    - `could_not_run` integer
    - `running` integer
  - `failed_safety_checks` string[]: Attached safety checks that did not pass
  - `run_ids` string[]
  - `attached_since_tested` string[]: Tests the agent runs now that this revision was not tested on
  - `replaces_live_revision_number` integer, nullable: The live version that making this one live replaces, when this one was made from an earlier version
  - `phone_call_count` integer: Phone calls this revision answered
  - `session_count` integer: Chat, email and workflow sessions this revision ran
  - `evaluated_at` string, date-time, nullable
  - `published_at` string, date-time, nullable
  - `mentium_created_at` string, date-time, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/mentium/apis/mentium-api.md) - [All operations](https://skmtc.dev/mentium/apis/mentium-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mentium/apis/mentium-api/revisions/b4ed8e59432e?raw)