--- title: "Record the outcome of reviewing a finished test-authoring session" method: POST path: "/agentSession/{id}/review" tags: ["AgentSession"] --- # Record the outcome of reviewing a finished test-authoring session `POST /agentSession/{id}/review` Records what the user decided about a finished `test_authoring` session, flipping it to the reviewed outcome: `accepted` when they kept the authored work, `closed` when they discarded it. A status write only, unless the caller opts into `delete_test` alongside `closed` — see that field. Nothing is ever deleted implicitly, and no branch is deleted at all. Valid for creation and edit sessions alike. Granted only from `completed` or `needs_attention`, enforced inside the write transaction; every other status is a 409, including an already-reviewed session, so a repeated call is rejected rather than silently succeeding. Session-level like `merged` (the cloud instance keeps its own status) and terminal: a reviewed session cannot be resumed, reviewed again, spawned on, or have its status rewritten through updateAgentSession. The conversation is retained either way, so a closed task can be regenerated from it. ## Path parameters - `id` string, required ## Request body - ReviewAgentSessionRequest — Request to record a review outcome on a finished authoring session - `outcome` 'accepted' | 'closed', required — What the user decided about a finished authoring task. `accepted` keeps the authored work; `closed` discards the task. Neither deletes anything on its own; a caller closing a task can additionally ask for its test to be deleted via `delete_test`. Both are terminal session-level statuses — see AgentInstanceStatus, whose values these mirror. - `delete_test` boolean — (Optional) Delete the test this session saved, as part of closing it. Valid only with the `closed` outcome; sending it with `accepted` is a 400. The caller must hold write access to journeys in the session's workspace, the same permission deleting the test directly would need. The test is identified from the session (`startup_params.test_id`, else its one remote `Test` artifact) rather than named by the caller, and only a test the session itself authored is deletable — established from `authoring_mode` and from the test having been created after the session began, either of which refusing on its own. A session with no saved test, several with nothing to single one out, or one it did not author, and a test that cannot be deleted, are each a 409 with nothing closed — as is the session itself changing between the target being resolved and the close. The TEST is deliberately not version-pinned: a concurrent edit to it does not block the deletion, which removes the test rather than a particular version of it. Nothing else is deleted — flows cascade as they do for any test deletion, and the branch is untouched. ## Response `200` The agent session, now holding the reviewed outcome - AgentSession - `id` string, required — The id of the agent session - `workspace_id` string, required — The id of the workspace - `created_time` integer, required — The timestamp of the agent session creation in epoch milliseconds - `created_by_id` string, required — The id of the user who created the agent session - `last_updated_time` integer, required — The timestamp of the agent session last update in epoch milliseconds - `last_updated_by_id` string, required — The id of the user who last updated the agent session - `agent_type` 'test_authoring' | 'test_creation_planning' | 'test_planning' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'test_recovery' | 'runtime_recovery_summary_agent' | 'plan_run_analysis' | 'deployment_analysis' | 'workspace_results_analysis' | 'results_auto_analysis' | 'workspace_assistant' | 'app_modeling' | 'app_modeling_run' | 'file_assertion' | 'test_impact' | 'test_impact_shadow' | 'repair_notes', required - `is_trial` boolean, required — Whether this agent session is associated with a trial account - `parent_session_id` string — The id of the parent agent session - `initiating_request_id` string — A unique identifier for the request that initiated this agent session. If set, this must be globally unique and requests to create a new agent session with the same initiating_request_id will fail. - `startup_params` union - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'workspace_assistant' | 'app_modeling' | 'app_modeling_run' | 'file_assertion' | 'test_impact' | 'test_impact_shadow' | 'repair_notes', required - `parent_session_id` string — The id of the parent session to review - `system_prompt` string — The system prompt that defines the review goals and instructions - `agent_subtype` 'test_authoring_analysis' | 'results_analysis_analysis' | 'failure_categorization_analysis' | 'failure_categorization_override_analysis' — Subtype for agent_review agents to distinguish different review purposes - `test_id` string — Optional test ID to give the review agent access to test definition and analysis tools - `test_run_id` string — Optional test run ID to give the review agent access to test run analysis tools - `plan_run_id` string — Optional plan run ID for results-analysis reviews of plan-run RAA sessions - `deployment_event_id` string — Optional deployment event ID for results-analysis reviews of deployment RAA sessions - `batch_id` string — Optional identifier linking reviews from the same backfill or batch run - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'workspace_assistant' | 'app_modeling' | 'app_modeling_run' | 'file_assertion' | 'test_impact' | 'test_impact_shadow' | 'repair_notes', required - `application_id` string — The id of the application to analyze - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'workspace_assistant' | 'app_modeling' | 'app_modeling_run' | 'file_assertion' | 'test_impact' | 'test_impact_shadow' | 'repair_notes', required - `test_run_id` string — The ID of the test run this session is scoped to - `agent_state` NextStepGenerationState — Agent model state tracked between generation requests - `entireTestPlan` TestCreationOutline — A test outline with tasks and suggested flows and snippets - `test_case` string, required — A clear description of the test case to be performed - `tasks` TestCreationTaskPlan[], required — A list of tasks to be performed - `task` string, required — A clear description of the task to be performed - `suggested_validation` string, required — Description of what to validate when this task is complete - `suggested_flow_options` TestCreationFlowOption[], required — List of recommended flow options for this task - … - `suggested_snippet_options` TestCreationSnippetOption[], required — List of recommended code snippet options for this task - … - `implementation_notes` string — Notes about how to create a good task for the plan, including information from relevant screenshots if available - `screenshots_cited` TestGenerationScreenshotReference[], required — List of screenshots cited in the implementation notes - … - `implementation_notes` string — Notes about how to create a good test from the plan, including when to use variables and important validations - `testInformation` TestCreationPlanningTestInformation — Test configuration and metadata selected during planning - `test_id` string — The ID of an existing test to edit instead of creating a new one - `test_variant_id` string — The variant (version) ID of the test being edited. Distinct from `test_id`, which is the invariant test identity — `test_variant_id` pins a specific snapshot. Set when the caller wants the edit applied against a known version (for example, to dedup auto-triggered edits for the same version). - `source_test_id` string — The invariant ID of an existing test to COPY as the starting point for a brand new test. The source test is only read — it is never modified — and the test that gets created is a new, independent test. Mutually exclusive with `test_id`, which edits an existing test in place rather than copying it. Set this when the user wants to start from an existing test ("make a copy of X and then ...") and leave `test_id` unset. - `name` string — The name of the test - `description` string — The description of the test - `application_id` string — The ID of the application for the test - `environment_id` string — The ID of the environment for the test - `deployment_id` string — The ID of the deployment for the test - `test_case` string — The test case for the test - `url_override` string — The base URL for the test, if there is no application or if the application's base URL should be overridden for this test - `credentials_id` string — The ID of the credentials for the test - `http_auth_credentials_id` string — The ID of the HTTP Basic Auth credentials for the test - passed in the HTTP request, as opposed to the interactive login credentials in credentials_id - `test_type` 'api' | 'browser' | 'performance' | 'mobile' — Type of test - `viewport_width` integer — Browser viewport width in pixels - `viewport_height` integer — Browser viewport height in pixels - `datatable_id` string — The ID of the data table for data-driven tests - `scenario_id` string — The ID of a specific scenario within the data table - `labels` string[] — Labels to apply to the test - `branch_id` string — The ID of the branch to save the test to (the save-to / destination branch) - `source_branch_id` string — The ID of the branch to load the test from as the starting point for edits. Only meaningful when test_id is set (editing an existing test). When unset, the test is loaded from master (it does NOT fall back to branch_id). This is the load-from branch; branch_id remains the save-to (destination) branch. - `plan_id` string — The ID of the plan to add the test to after creation - `device_preset` 'blackberry_playbook' | 'blackberry_z30' | 'galaxy_fold' | 'galaxy_note_3' | 'galaxy_note_ii' | 'galaxy_s5' | 'galaxy_s6' | 'galaxy_s8' | 'galaxy_s21' | 'galaxy_s22' | 'galaxy_s23' | 'galaxy_s_iii' | 'galaxy_tab_s7' | 'ipad' | 'ipad_air_2020' | 'ipad_mini' | 'ipad_mini_4' | 'ipad_pro' | 'ipad_ten_point_two' | 'iphone_11_pro_max' | 'iphone_11' | 'iphone_12' | 'iphone_12_pro_max' | 'iphone_13_mini' | 'iphone_13' | 'iphone_13_pro' | 'iphone_13_pro_max' | 'iphone_14' | 'iphone_14_pro' | 'iphone_14_plus' | 'iphone_14_pro_max' | 'iphone_15' | 'iphone_15_plus' | 'iphone_15_pro' | 'iphone_15_pro_max' | 'iphone_4' | 'iphone_5_se' | 'iphone_6_7_8' | 'iphone_6_7_8_plus' | 'iphone_x' | 'jiophone_2' | 'kindle_fire_hdx' | 'laptop_with_hidpi_screen' | 'laptop_with_mdpi_screen' | 'laptop_with_touch' | 'lg_optimus_l70' | 'microsoft_lumia_550' | 'microsoft_lumia_950' | 'moto_g4' | 'nexus_4' | 'nexus_5' | 'nexus_5x' | 'nexus_6' | 'nexus_6p' | 'nexus_7' | 'nexus_10' | 'nokia_lumia_520' | 'nokia_n9' | 'pixel_2' | 'pixel_2_xl' | 'pixel_6' | 'surface_duo' — Preset device configuration - `device_orientation` 'portrait_primary' | 'portrait_secondary' | 'landscape_primary' | 'landscape_secondary' — Device orientation - `application_id` string — The ID of the application being tested - `environment_id` string — The ID of the environment being tested - `url` string — The URL to start testing from - `agent_session_source` 'user_web' | 'user_mcp' | 'user_cli' | 'auto_tra' | 'user_tra' | 'unknown' — Origin of an agent session — who or what initiated it. `user_web`, `user_mcp`, `user_cli` distinguish the human-driven entry point. `auto_tra` marks sessions automatically started by the Test Recovery Agent (runtime recovery). `user_tra` marks edits the user explicitly accepted from a TRA suggestion. `unknown` is used when no source was provided. - `authoring_mode` 'creation' | 'edit' — Whether a `test_authoring` session authored a new test or started from one that already existed. Absent is not `creation` — it means the session predates the field and the answer was never recorded; a consumer acting destructively must treat the two differently. - `xray_binding_issue_id` string — (Optional) The Jira issue id of the Xray test case this session binds the test it saves to. Resolved server-side at session creation from the references the planning session copied onto this one, and only when the creating caller was authorized to create TCM bindings in this workspace — the binding is provenance the user delegated at creation, so it is frozen here rather than re-read later from a manifest any holder of session write can restate. Never rewritten afterwards, and a value supplied by the caller is ignored. Absent when the caller was unauthorized, when the session references no Xray case or more than one, or when the integration does not belong to this workspace. Meaningless without `xray_binding_integration_id`, which names the Jira site that resolves it. - `xray_binding_integration_id` string — (Optional) The Xray workspace integration naming the Jira site that resolves `xray_binding_issue_id`. Resolved server-side at session creation under the same conditions as that field and checked then to belong to this session's workspace; never rewritten, and a value supplied by the caller is ignored. Set and cleared only together with `xray_binding_issue_id`. - `test_variant_id` string — The variant (version) ID of the test being edited, when this session is an edit of a specific known version. Set in conjunction with `test_information.test_id`. - `resume_cursor` string — Optional 1-based-inclusive index of the last saved step the next instance replays before continuing the LLM loop (e.g. "5" replays steps 1–5; absent or "0" replays nothing). Set by the resume planner on continue via `PATCH /agentSession/{id}/startupParams`; not used at session creation. - `test_id` string — The invariant id of the test this authoring session operates on. Set at session creation for edits (mirrored from `test_information.test_id`) and rolled forward by the cloud TAA continuation flow at each save/pause via `PATCH /agentSession/{id}/startupParams`, so a resuming instance continues the same test rather than authoring a new one. - `branch_id` string — (Optional) The id of the save-to branch — every test and flow version the agent writes lands on it, leaving master untouched. Set once at session creation and mirrored from `test_information.branch_id`; a supplied name is canonicalized to the id, which must resolve inside the session's workspace. An edit session (`test_id` set) that omits it gets a server-created feature branch unless the workspace sets `require_agent_edits_on_branches: false`; creation sessions author on master. Absent on local sessions, which carry the value on `test_information`. A resume reuses it. The branch outlives the session and is closed only by a merge into master (via the branch merge endpoint or `auto_merge`), which is also what flips the session to `merged`. - `source_branch_id` string — (Optional) The id of the load-from branch — the branch the agent reads the starting test version from. Mirrored from `test_information.source_branch_id` at session creation. The agent never saves to it (it saves to `branch_id`); when unset, the version loads from master (it does NOT fall back to `branch_id`). Only meaningful for edit sessions. - `base_version` integer — (Optional) The immutable source-branch version number the edit LOADED FROM — the variant of the `source_branch_id` branch (or master, when unset) at the moment the runtime fetched the starting test. Written once by the runtime at initial load and never rolled forward, so it pins the "Review changes" diff baseline to the version actually edited rather than the source branch's current tip (which can advance while the edit is in flight). Only meaningful for edit sessions; absent on older sessions, where consumers fall back to the source branch's current version tag. - `auto_merge` boolean — When true, the session's `branch_id` is merged into master on a successful session completion (provided the branch still resolves to this workspace and has new versions). Defaults to absent/false — the branch is left open for human review. - `repair_notes_session_id` string — The runtime repair notes session whose finding seeded this edit - `impact_session_id` string — (Optional) The test impact analysis session this authoring session answers — the reverse half of the link whose forward half is a remote artifact of kind `AgentSession` on that impact session. Provenance only: nothing is granted by it and nothing dereferences it, and like every other startup_params field it is only as trustworthy as the credential that wrote the session. The initiate endpoint (`initiateTestAuthoringSession`) checks that it exists, is in the same workspace and is a `test_impact` session; this generic create path does not, so a session written directly here can carry an unchecked value. Deliberately NOT `parent_session_id`, which on this path means the planning session whose artifacts are copied into this one. - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'workspace_assistant' | 'app_modeling' | 'app_modeling_run' | 'file_assertion' | 'test_impact' | 'test_impact_shadow' | 'repair_notes', required - `test_run_id` string — The ID of the test run to analyze - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'workspace_assistant' | 'app_modeling' | 'app_modeling_run' | 'file_assertion' | 'test_impact' | 'test_impact_shadow' | 'repair_notes', required - `plan_run_id` string — The ID of the plan run to analyze - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'workspace_assistant' | 'app_modeling' | 'app_modeling_run' | 'file_assertion' | 'test_impact' | 'test_impact_shadow' | 'repair_notes', required - `deployment_event_id` string — The ID of the deployment event to analyze - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'workspace_assistant' | 'app_modeling' | 'app_modeling_run' | 'file_assertion' | 'test_impact' | 'test_impact_shadow' | 'repair_notes', required - `training_session_id` string — Optional training session ID for tracing - `test_run_id` string — The ID of the test run this session is scoped to - `repair_notes_session_id` string — (Optional) The runtime repair notes session whose finding seeded this edit. Set on the planning session that the improve-from-run flow opens and inherited by its child authoring session, so the branch compare can name the note an edit came from and the discard-rate metric can tell an accepted repair spec from an unrelated edit. Provenance only: it records which session's note was in front of the user, never that the user agreed with it, and never an authorization input. Absent on every session not started from a repair note. - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'workspace_assistant' | 'app_modeling' | 'app_modeling_run' | 'file_assertion' | 'test_impact' | 'test_impact_shadow' | 'repair_notes', required - `application_id` string — The id of the application the app modeling session builds a knowledge graph for - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'workspace_assistant' | 'app_modeling' | 'app_modeling_run' | 'file_assertion' | 'test_impact' | 'test_impact_shadow' | 'repair_notes', required - `application_id` string — The id of the application this coordinator run models - object - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'workspace_assistant' | 'app_modeling' | 'app_modeling_run' | 'file_assertion' | 'test_impact' | 'test_impact_shadow' | 'repair_notes', required - `test_run_id` string — The ID of the test run this file assertion evaluation belongs to. - object — Context for a test impact analysis session. Test impact sessions are written under the server-agents service credential rather than the caller's, so created_by_id identifies the service account and not the requester — the initiating identity is recorded here instead. Trust level: these fields are reported by the service that creates the session, not derived server-side from the authenticated principal, so like every other startup_params field they are only as trustworthy as the credential that wrote the session. Treat them as provenance for internal review, never as an authorization or audit input. - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'workspace_assistant' | 'app_modeling' | 'app_modeling_run' | 'file_assertion' | 'test_impact' | 'test_impact_shadow' | 'repair_notes', required - `application_id` string — The id of the application the impact analysis was scoped to - `initiating_user_id` string — The id of the user who requested the analysis, when the request carried a user identity. Absent for API key callers, which have no associated user; see initiating_auth_type to tell that case apart from an identity that was simply not recorded. - `initiating_auth_type` 'user' | 'api_key' — The authentication mode of the caller that initiated a test impact analysis. `api_key` callers carry no user identity, so initiating_user_id is expected to be absent for them. - `references` ChangeReference[] — (Optional) The normalized change references the analysis was requested for. Provenance: they are what group this analysis with the other analyses, deployments and runs of the same change. Nothing is granted by them and nothing dereferences them. - `type` 'pull_request' | 'commit' | 'branch' | 'issue' | 'test_case' | 'release' | 'custom', required — The kind of thing the reference names, which decides how mabl normalizes the id. - `id` string — The identifier in the owning system, e.g. "github.com/mablhq/ui#3341", "9f2c1ab", "MABL-21839". For a pull_request the host is part of the canonical key, so a hostless id such as "mablhq/ui#3341" is a different reference from "github.com/mablhq/ui#3341" and the two never group together; supply the pull request url, either here or in url, and mabl derives the host-qualified form. Required unless url is given and parseable. Whitespace and the characters < > " are rejected, as is a backslash: url parsers read one as a path separator, so a value carrying it names a different thing than it reads as. - `url` string, uri — Optional link. Rendered, never parsed for meaning, except to derive the canonical id for a pull_request. When both are given and both name a pull request, they must name the same one. Held to http or https, and rejected for whitespace, < > " or a backslash - a backslash is a path separator to a url parser and an ordinary character to a reader, so one url would name two hosts. - `revision` string — (Optional) The revision the analysis was requested for, same meaning as a deployment event's revision. The per-commit key for lining an analysis up with that commit's deployments and runs. - `mabl_branch` string — (Optional) The mabl branch the analysis read tests on. Absent when it read master. - object — Context for a hidden shadow session that replays a completed test impact analysis session under an experimental variant for internal comparison. Not part of any customer-visible flow; see TestImpactSessionStartupParams for the session being shadowed. application_id, shadow_of_session_id, variant and replicate are required for this session type but are not declared `required` here: the anyOf members flatten into one generated interface, so a required field on one shape becomes required on all of them (see the test_run_id comment on RepairNotesSessionStartupParams below). Enforced by the caller instead. - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'workspace_assistant' | 'app_modeling' | 'app_modeling_run' | 'file_assertion' | 'test_impact' | 'test_impact_shadow' | 'repair_notes', required - `application_id` string — The id of the application the impact analysis was scoped to - `shadow_of_session_id` string — The id of the original test_impact session this shadow replays - `variant` string — The experimental condition this replay ran under (e.g. baseline, no_knowledge_graph). A free-form value on purpose: a new condition is a new value, never a schema change. - `replicate` integer — 1-based index distinguishing repeated shadow replays of the same original session and variant. Part of the derived idempotency key that keeps a re-run of the same batch window from double-creating a shadow session. - `include_plans` boolean — Whether the replay assumed the original session's plan associations. - object — Context for a runtime repair notes session: the test run whose failure is being diagnosed. test_run_id is required. - `type` 'test_authoring' | 'agent_review' | 'app_summary' | 'test_run_analysis' | 'plan_run_analysis' | 'deployment_analysis' | 'results_auto_analysis' | 'test_creation_planning' | 'test_planning' | 'workspace_assistant' | 'app_modeling' | 'app_modeling_run' | 'file_assertion' | 'test_impact' | 'test_impact_shadow' | 'repair_notes', required - `test_run_id` string — The ID of the test run this session is scoped to - `messages` AgentSessionMessage[], required — The messages in the agent session - union - BaseMessage - `id` string, required — The id of the message - `message_index` integer — The index of the message in the session (used for ordering) - `timestamp` integer, required — The timestamp of the message in epoch milliseconds - `metadata` object — The metadata of the message - `parts` MessagePart[], required - union - object - … - object - … - object - … - object - … - object - … - object — Code the model asked the Gemini built-in Python execution sandbox to run. Emitted alongside a matching CodeExecutionResultPart on the same model turn — the sandbox runs synchronously and returns its result in the same response. Only appears when the agent enables the code execution tool and the model chooses to use it. - … - object — The result of the sandbox executing the immediately preceding CodeExecutionCallPart. Bundled with the call on the same model turn; there is no separate tool-output round-trip. - … - `role` 'user' | 'model' | 'tool_output' | 'special', required - BaseMessage - `id` string, required — The id of the message - `message_index` integer — The index of the message in the session (used for ordering) - `timestamp` integer, required — The timestamp of the message in epoch milliseconds - `metadata` object — The metadata of the message - `parts` MessagePart[], required - union - object - … - object - … - object - … - object - … - object - … - object — Code the model asked the Gemini built-in Python execution sandbox to run. Emitted alongside a matching CodeExecutionResultPart on the same model turn — the sandbox runs synchronously and returns its result in the same response. Only appears when the agent enables the code execution tool and the model chooses to use it. - … - object — The result of the sandbox executing the immediately preceding CodeExecutionCallPart. Bundled with the call on the same model turn; there is no separate tool-output round-trip. - … - `role` 'user' | 'model' | 'tool_output' | 'special', required - BaseMessage - `id` string, required — The id of the message - `message_index` integer — The index of the message in the session (used for ordering) - `timestamp` integer, required — The timestamp of the message in epoch milliseconds - `metadata` object — The metadata of the message - `parts` MessagePart[], required - union - object - … - object - … - object - … - object - … - object - … - object — Code the model asked the Gemini built-in Python execution sandbox to run. Emitted alongside a matching CodeExecutionResultPart on the same model turn — the sandbox runs synchronously and returns its result in the same response. Only appears when the agent enables the code execution tool and the model chooses to use it. - … - object — The result of the sandbox executing the immediately preceding CodeExecutionCallPart. Bundled with the call on the same model turn; there is no separate tool-output round-trip. - … - `role` 'user' | 'model' | 'tool_output' | 'special', required - BaseMessage - `id` string, required — The id of the message - `message_index` integer — The index of the message in the session (used for ordering) - `timestamp` integer, required — The timestamp of the message in epoch milliseconds - `metadata` object — The metadata of the message - `parts` MessagePart[], required - union - object - … - object - … - object - … - object - … - object - … - object — Code the model asked the Gemini built-in Python execution sandbox to run. Emitted alongside a matching CodeExecutionResultPart on the same model turn — the sandbox runs synchronously and returns its result in the same response. Only appears when the agent enables the code execution tool and the model chooses to use it. - … - object — The result of the sandbox executing the immediately preceding CodeExecutionCallPart. Bundled with the call on the same model turn; there is no separate tool-output round-trip. - … - `role` 'user' | 'model' | 'tool_output' | 'special', required - `instance_ids` string[] — IDs of all cloud instances created for this session (in chronological order). Empty for local-client-driven sessions. - `instance_type` 'cloud' | 'local' — Indicates what kind of agent instance is driving a session. `cloud` means a server-managed cloud instance owns the lifecycle (created via the cloudInstance endpoints). `local` means a local client (e.g. mabl CLI) is driving the session via updateAgentSession. - `latest_instance_status` 'queued' | 'running' | 'needs_attention' | 'completed' | 'failed' | 'terminated' | 'terminating' | 'rate_limited' | 'skipped' | 'merged' | 'accepted' | 'closed' | 'resuming' | 'none' — The status of the latest agent instance driving a session. The same enum is used for cloud and local instances. Cloud-only values (`queued`, `terminating`, `rate_limited`, `skipped`) are set by the cloud instance lifecycle (start/terminate/end). Common values (`running`, `needs_attention`, `completed`, `failed`, `terminated`) are written by either cloud or local clients. `merged` is a session-level state applied after a `completed` authoring task's branch is merged into master (via the branch merge endpoint or the session's `auto_merge` setting); the underlying cloud instance stays `completed`. `accepted` and `closed` are session-level review outcomes for a finished authoring task, set only through the review endpoint; the underlying cloud instance keeps its own status. `accepted` records that the user kept the authored test. `closed` records that the user discarded it; the session's test is left in place unless the caller asked for it to be deleted (`delete_test` on the review request), no branch is deleted either way, and the session's conversation is retained so the task can be regenerated from it. Both are terminal in the same sense as `merged` — neither is resumable, and no lifecycle transition leaves them. `resuming` is a transient, server-set-only state on the session (no instance holds it) — the cloud TAA continuation flow flips a resumable session to `resuming` while it plans the answer, then to `queued` when the new instance spawns (or back to a resumable status on re-clarification, or `failed` on error). It is the concurrency guard, so a second answer to a `resuming` session is rejected. The session's `instance_type` field indicates which kind of instance owns the session. Use `none` in query parameters to match sessions without any status. - `latest_termination_reason` 'execution_timeout' | 'stop_requested' | 'infra_shutdown' | 'dispatch_failed' | 'agent_stalled' | 'agent_error' | 'unknown' — The reason for terminating a cloud instance. 'infra_shutdown' covers any shutdown signal from the runtime environment (K8s pod eviction, Cloud Run instance cycling, etc.) — kept generic so it applies regardless of where the agent runs. 'dispatch_failed' means the instance never started — its start message failed to publish, or expired in the queue before any runner claimed it. 'agent_stalled' means the agent was still alive but stopped making progress, so a watchdog hard-killed it. 'agent_error' means the agent threw or exited unexpectedly while its work was still in flight. - `related_artifacts` Artifact[] — Artifacts related to this agent session (e.g., generated tests, flows, etc.). Visible to all workspace members via queryAgentSessions — do not store creator-private content here; use `messages` for private content. - union - BaseArtifact - `artifact_type` 'inline' | 'remote', required — The type of artifact - BaseArtifact - `artifact_type` 'inline' | 'remote', required — The type of artifact - `agent_variant` string — The authoring-agent arm assigned to this session at creation time (values: `generic` or `flexible`). Records which test-authoring agent variant the runtime should use for the session. Only set for `test_authoring` sessions; unset for other agent types. ## Other responses - `400` — Invalid or missing parameter - `401` — User not authenticated - `403` — User not authorized - `404` — Entity not found - `409` — Conflicts with the current state of the resource - `default` — Unknown error --- [API](https://skmtc.dev/mabl/apis/mabl-api.md) · [All operations](https://skmtc.dev/mabl/apis/mabl-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mabl/apis/mabl-api/revisions/24dd8c2933df?raw)