---
title: "Open one bounded CommerceAgent run"
method: POST
path: "/v1/commerce/mcp/agent/runs"
---

# Open one bounded CommerceAgent run

`POST /v1/commerce/mcp/agent/runs`

## Request

- Base URL: `https://api.decionis.com`
- URL: `https://api.decionis.com/v1/commerce/mcp/agent/runs`
- Auth: HTTP bearer

Binds the run to the credential's organization. The objective fixes the admissible action families; the platform scope, action budget, currency-exposure budget and horizon (at most 31 days) bound every later proposal. The same idempotency key replays the same run; a rebound key is 409. Nothing is evaluated or executed.

## Headers

- `Idempotency-Key` string, required

## Request body

- Mandate
  - `objective` 'hold_margin_floor' | 'hold_inventory_floor' | 'review_orders' | 'review_refunds' | 'review_promotions' | 'release_payments', required
  - `scope` object, required
    - `platforms` string[], required
    - `skus` string[]
    - `order_ids` string[]
  - `budget` object, required
    - `actions` integer, required
    - `exposure` object, required
      - `amount` number, required
      - `currency` string, required
  - `horizon` object, required
    - `ends_at` string, date-time, required
  - `agent` object, required
    - `id` string, required
  - `idempotency_key` string, required
  - `confirmation` unknown, required

## Response `200`

Validated bounded response; private, no-store

- StartResponse
  - `run` object, required
    - `version` 'commerce-agent-run-v1', required
    - `run_id` string, uuid, required
    - `org_id` string, uuid, required
    - `state` 'active' | 'stopped' | 'exhausted' | 'expired', required
    - `objective` 'hold_margin_floor' | 'hold_inventory_floor' | 'review_orders' | 'review_refunds' | 'review_promotions' | 'release_payments', required
    - `allowed_action_types` string[], required
    - `scope` object, required
      - `platforms` string[], required
      - `skus` string[]
      - `order_ids` string[]
    - `agent` object, required
      - `id` string, required
    - `budget` object, required
      - `actions` object, required
        - `granted` integer, required
        - `used` integer, required
        - `remaining` integer, required
      - `exposure` object, required
        - `granted` number, required
        - `used` number, required
        - `remaining` number, required
        - `currency` string, required
    - `horizon` object, required
      - `started_at` string, date-time, required
      - `ends_at` string, date-time, required
    - `proposals` object, required
      - `count` integer, required
      - `by_outcome` object, required
        - `PROCEED` integer, required
        - `HOLD` integer, required
        - `ESCALATE` integer, required
        - `BLOCK` integer, required
      - `refused` integer, required
      - `recent` object[], required
        - `proposal_id` string, uuid, required
        - `action_type` 'PRICE_CHANGE' | 'INVENTORY_MUTATION' | 'ORDER_ACCEPTANCE' | 'FULFILLMENT_ACTION' | 'PROMOTION_CHANGE' | 'REFUND_REQUEST' | 'RETURN_AUTHORIZATION' | 'PAYMENT_RELEASE' | 'VENDOR_BANK_CHANGE' | 'EARLY_PAYMENT_DISCOUNT' | 'CREDIT_HOLD_RELEASE', required
        - `platform` string, required
        - `outcome` 'PROCEED' | 'HOLD' | 'ESCALATE' | 'BLOCK', required
        - `dossier_id` string, uuid, nullable, required
        - `amount` number, nullable, required
        - `recorded_at` string, date-time, required
    - `stop` object, nullable, required
      - `reason` string, required
      - `stopped_at` string, date-time, required
    - `agent_cost` object, required
      - `proposals` integer, required
      - `input_tokens` integer, required
      - `output_tokens` integer, required
      - `amount` number, required
      - `currency` string, nullable, required
    - `durability` 'process_memory' | 'backend_ledger', required
    - `execution_available` unknown, required
    - `no_downstream_action_executed` unknown, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `replayed` boolean, required

## Other responses

- `400`: Malformed, unconfirmed, mismatched or dossier-less PROCEED input
- `401`: Missing or invalid credential
- `403`: Write scope, role or dossier access denied
- `404`: Feature disabled, run or dossier unavailable to this organization
- `409`: Rebound idempotency key or dossier mismatch; never automatically retry a write
- `413`: Request exceeds route byte limit
- `429`: Durable identity/IP limit exceeded; Retry-After supplied
- `503`: Authority, storage or evidence unavailable; completion may be unconfirmed

---

[API](https://skmtc.dev/decionis/apis/decionis-commerce-gate-api.md) · [All operations](https://skmtc.dev/decionis/apis/decionis-commerce-gate-api/llms.txt) · [OpenAPI document](https://skmtc.dev/decionis/apis/decionis-commerce-gate-api/revisions/9fecb7109bf8?raw)