Procurement

Submit a natural-language request

POST
/procurement/requests

Submit a natural-language request. Requires the MANAGER role. Idempotent: send an Idempotency-Key.

Authorization

__Host-qm_session<token>

Session cookie set by sign-in on HTTPS deployments (the hosted demo).

In: cookie

Header Parameters

X-Requested-With*string

CSRF guard: must be quartermaster on every mutation.

Idempotency-Key*string

A unique key per user action; retries with the same key return the first result.

Length8 <= length <= 128

Request Body

application/json

A natural-language purchasing instruction for the agent.

A natural-language purchasing instruction for the agent.

instruction*string

The natural-language instruction from the restaurant.

Length3 <= length <= 2000
currency?"USD"

ISO 4217 currency code.

Default"USD"

Value in

  • "USD"
budget_limit_minor?integer

Budget limit, in minor units (cents).

Range0 <= value <= 9007199254740991
required_by?string

Date the goods are needed by (YYYY-MM-DD).

Match^\d{4}-\d{2}-\d{2}$
allow_alternatives?boolean
Defaulttrue
demand_multiplier?number

Demand relative to normal (1 = normal, 1.25 = 25% busier).

Range0.25 <= value <= 4

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/procurement/requests" \  -H "X-Requested-With: quartermaster" \  -H "Idempotency-Key: 3b8c2c1e-6f6d-4a59-9a43-8f0c2a9e1d22" \  -H "Content-Type: application/json" \  -d '{    "instruction": "We\'re expecting a busy weekend. Restock takeaway containers and cooking oil without exceeding $300.",    "currency": "USD",    "allow_alternatives": true  }'
{  "id": "string",  "status": "DRAFT",  "instruction": "string",  "currency": "string",  "budget_limit_minor": 0,  "required_by": "string",  "allow_alternatives": true,  "intent": {    "inventory_item_ids": [      "string"    ],    "demand_multiplier": 0,    "budget_limit_minor": 0,    "required_by": "string",    "notes": "string",    "unsupported_requests": [      "string"    ],    "ai_mode": "LLM"  },  "forecast": {    "id": "string",    "demand_multiplier": 0,    "created_at": "string",    "method": "REORDER_POINT_V1",    "lines": [      {        "inventory_item_id": "string",        "sku": "string",        "name": "string",        "unit": "string",        "base_daily_usage": 0,        "demand_multiplier": 0,        "forecast_daily_usage": 0,        "lead_time_days": 0,        "safety_stock": 0,        "coverage_days": 0,        "on_hand": 0,        "inbound_confirmed": 0,        "committed": 0,        "available": 0,        "reorder_point": 0,        "target_stock": 0,        "needs_reorder": true,        "suggested_quantity": 0,        "explanation": "string"      }    ]  },  "market": [    {      "inventory_item_id": "string",      "reference_unit_price_minor": 0,      "sample_size": 0,      "observed_at": "string",      "status": "AVAILABLE",      "quotes": [        {          "id": "string",          "source": "CHANNEL3_MARKET",          "title": "string",          "merchant_domain": "string",          "url": "string",          "price_minor": 0,          "currency": "string",          "pack_quantity": 0,          "normalized_unit_price_minor": 0,          "comparable": true,          "observed_at": "string",          "availability": "string"        }      ]    }  ],  "candidates": [    {      "id": "string",      "inventory_item_id": "string",      "supplier_id": "string",      "supplier_name": "string",      "supplier_approved": true,      "checkout_eligible": true,      "catalog_item_id": "string",      "sku": "string",      "title": "string",      "pack_quantity": 0,      "packs": 0,      "units": 0,      "item_subtotal_minor": 0,      "shipping_minor": 0,      "tax_minor": 0,      "fees_minor": 0,      "delivered_total_minor": 0,      "delivered_unit_cost_minor": 0,      "lead_time_days": 0,      "rank": 0,      "eligible": true,      "ineligible_reasons": [        "string"      ],      "quarantined": true,      "data_source": "CHANNEL3_MARKET"    }  ],  "proposals": [    {      "id": "string",      "number": "string",      "request_id": "string",      "supplier_id": "string",      "supplier_name": "string",      "status": "PROPOSED",      "currency": "string",      "subtotal_minor": 0,      "shipping_minor": 0,      "tax_minor": 0,      "fees_minor": 0,      "total_minor": 0,      "cart_hash": "string",      "items": [        {          "id": "string",          "kind": "PRODUCT",          "sku": "string",          "description": "string",          "category": "food_packaging",          "quantity": 0,          "unit_price_minor": 0,          "line_total_minor": 0,          "inventory_item_id": "string",          "pack_quantity": 0        }      ],      "policy_decision": {        "id": "string",        "purchase_order_id": "string",        "decision": "ALLOW",        "violations": [          {            "code": "MANDATE_INACTIVE",            "severity": "BLOCK",            "message": "string",            "evidence": {}          }        ],        "checks": [          {            "code": "string",            "passed": true,            "detail": "string"          }        ],        "human_approval_required": true,        "mandate_version": 0,        "policy_version": "string",        "input_digest": "string",        "evaluated_at": "string"      },      "certificate": {        "id": "string",        "status": "ACTIVE",        "payload": {          "certificate_version": 1,          "intent_id": "string",          "organization_id": "string",          "buyer_id": "string",          "purchase_order_id": "string",          "supplier_id": "string",          "cart_hash": "string",          "mandate_id": "string",          "mandate_version": 0,          "policy_decision_id": "string",          "currency": "string",          "approved_amount_minor": 0,          "approved_at": "string",          "expires_at": "string",          "nonce": "string",          "key_id": "string"        },        "key_id": "string",        "signature": "string",        "algorithm": "Ed25519",        "issued_at": "string",        "expires_at": "string"      },      "payment": {        "id": "string",        "intent_id": "string",        "purchase_order_id": "string",        "status": "CREATED",        "paypal_order_id": "string",        "paypal_capture_id": "string",        "amount_minor": 0,        "currency": "string",        "captured_amount_minor": 0,        "refunded_amount_minor": 0,        "failure_code": "string",        "failure_message": "string",        "created_at": "string",        "updated_at": "string",        "completed_at": "string"      },      "delivery": {        "id": "string",        "purchase_order_id": "string",        "supplier_id": "string",        "status": "SCHEDULED",        "expected_date": "string",        "original_expected_date": "string",        "delivered_at": "string",        "delay_reason": "string",        "data_source": "SYNTHETIC"      },      "created_at": "string"    }  ],  "active_proposal_id": "string",  "recommendation": {    "summary": "string",    "rationale": [      "string"    ],    "ai_mode": "LLM"  },  "security_findings": [    {      "id": "string",      "type": "PROMPT_INJECTION",      "severity": "LOW",      "title": "string",      "description": "string",      "source_kind": "string",      "source_id": "string",      "evidence": {},      "related_purchase_order_id": "string",      "related_request_id": "string",      "created_at": "string"    }  ],  "agent_steps": [    {      "id": "string",      "tool": "string",      "status": "SUCCEEDED",      "duration_ms": 0,      "summary": "string",      "started_at": "string"    }  ],  "created_by": "string",  "created_at": "string",  "updated_at": "string"}