{
  "schema_version": "2026-06-17.inference-market.v1",
  "product": "Flow Memory",
  "description": "AI-consumable endpoint index for the Flow Memory dry-run inference marketplace engine.",
  "safety_fields": {
    "dry_run_only": true,
    "funds_moved": false,
    "broadcast_allowed": false,
    "private_key_required": false,
    "live_trading_enabled": false,
    "legal_review_required": true,
    "compliance_review_required": true
  },
  "forbidden_request_material": [
    "raw_provider_credentials",
    "bearer_tokens_for_external_providers",
    "sensitive_signing_material",
    "value_transfer_instructions",
    "production_execution_flags",
    "broadcast_flags",
    "direct_execution_flags"
  ],
  "shared_contract_route_templates": [
    {"key": "marketList", "method": "GET", "route_template": "/inference/market/list", "path_fields": []},
    {"key": "modelDetail", "method": "GET", "route_template": "/inference/market/models/{model}", "path_fields": ["model"]},
    {"key": "feed", "method": "GET", "route_template": "/inference/market/feed", "path_fields": []},
    {"key": "buyerProfile", "method": "GET", "route_template": "/inference/buyers/{buyer_id}/profile", "path_fields": ["buyer_id"]},
    {"key": "sellerProfile", "method": "GET", "route_template": "/inference/sellers/{seller_id}/profile", "path_fields": ["seller_id"]},
    {"key": "providerAgentManifest", "method": "GET", "route_template": "/inference/providers/agent/manifest", "path_fields": []},
    {"key": "credentialRefs", "method": "POST|GET", "route_template": "/inference/credential-refs", "path_fields": []},
    {"key": "credentialRefRotate", "method": "PATCH", "route_template": "/inference/credential-refs/{credential_ref_id}/rotate", "path_fields": ["credential_ref_id"]},
    {"key": "credentialRefRevoke", "method": "POST", "route_template": "/inference/credential-refs/{credential_ref_id}/revoke", "path_fields": ["credential_ref_id"]},
    {"key": "providerEnroll", "method": "POST", "route_template": "/inference/providers/enroll", "path_fields": []},
    {"key": "providerPairingToken", "method": "POST", "route_template": "/inference/providers/{provider_id}/pairing-token", "path_fields": ["provider_id"]},
    {"key": "providerHeartbeat", "method": "POST", "route_template": "/inference/providers/{provider_id}/heartbeat", "path_fields": ["provider_id"]},
    {"key": "providerCatalog", "method": "POST", "route_template": "/inference/providers/{provider_id}/catalog", "path_fields": ["provider_id"]},
    {"key": "providerCapacity", "method": "POST", "route_template": "/inference/providers/{provider_id}/capacity", "path_fields": ["provider_id"]},
    {"key": "providerHealth", "method": "GET", "route_template": "/inference/providers/{provider_id}/health", "path_fields": ["provider_id"]},
    {"key": "marketOrders", "method": "POST", "route_template": "/inference/market/orders", "path_fields": []},
    {"key": "marketOrderCancel", "method": "POST", "route_template": "/inference/market/orders/{order_id}/cancel", "path_fields": ["order_id"]},
    {"key": "marketDepth", "method": "GET", "route_template": "/inference/market/depth", "path_fields": []},
    {"key": "marketReservations", "method": "POST", "route_template": "/inference/market/reservations", "path_fields": []},
    {"key": "paymentChallengePreview", "method": "POST", "route_template": "/inference/market/payment-challenge/preview", "path_fields": []},
    {"key": "analyticsUsage", "method": "GET", "route_template": "/inference/analytics/usage", "path_fields": []},
    {"key": "analyticsExport", "method": "GET", "route_template": "/inference/analytics/export", "path_fields": []}
  ],
  "endpoint_groups": [
    {
      "group": "marketplace_discovery",
      "summary": "Public marketplace discovery and profile records for dashboards and agents.",
      "endpoints": [
        {"method": "GET", "path": "/inference/market/list", "route_template": "/inference/market/list", "scope": "inference:read", "purpose": "List available market models and summary depth."},
        {"method": "GET", "path": "/inference/market/models/{model}", "route_template": "/inference/market/models/{model}", "scope": "inference:read", "purpose": "Return one model detail record.", "path_fields": ["model"]},
        {"method": "GET", "path": "/inference/market/feed", "route_template": "/inference/market/feed", "scope": "inference:read", "purpose": "Return recent dry-run marketplace feed records."},
        {"method": "GET", "path": "/inference/buyers/{buyer_id}/profile", "route_template": "/inference/buyers/{buyer_id}/profile", "scope": "inference:read", "purpose": "Return buyer marketplace profile metadata.", "path_fields": ["buyer_id"]},
        {"method": "GET", "path": "/inference/sellers/{seller_id}/profile", "route_template": "/inference/sellers/{seller_id}/profile", "scope": "inference:read", "purpose": "Return seller marketplace profile metadata.", "path_fields": ["seller_id"]},
        {"method": "GET", "path": "/inference/providers/agent/manifest", "route_template": "/inference/providers/agent/manifest", "scope": "inference:read", "purpose": "Return provider-agent public onboarding manifest metadata."}
      ]
    },
    {
      "group": "credential_refs",
      "summary": "Credential-reference lifecycle. Secret values are never accepted or returned.",
      "endpoints": [
        {
          "method": "POST",
          "path": "/inference/credential-refs",
          "route_template": "/inference/credential-refs",
          "scope": "inference:sell|inference:admin",
          "purpose": "Create a credential reference record.",
          "request_fields": ["owner_id", "workspace_id", "credential_ref", "provider_api", "display_name", "allowed_models", "metadata"],
          "response_fields": ["ok", "credential_ref", "secret_value_redacted", "raw_credentials_accepted", "safety_fields"]
        },
        {
          "method": "GET",
          "path": "/inference/credential-refs",
          "route_template": "/inference/credential-refs",
          "scope": "inference:read",
          "purpose": "List visible credential reference records without secrets.",
          "query_fields": ["owner_id", "workspace_id", "status", "provider_api"],
          "response_fields": ["ok", "credential_refs", "redaction", "safety_fields"]
        },
        {
          "method": "PATCH",
          "path": "/inference/credential-refs/{credential_ref_id}/rotate",
          "route_template": "/inference/credential-refs/{credential_ref_id}/rotate",
          "scope": "inference:admin",
          "purpose": "Rotate the credential reference pointer and invalidate stale provider routes.",
          "path_fields": ["credential_ref_id"],
          "request_fields": ["rotation_reason", "new_credential_ref", "operator_ticket"],
          "response_fields": ["ok", "credential_ref", "rotation", "routes_gated", "safety_fields"]
        },
        {
          "method": "POST",
          "path": "/inference/credential-refs/{credential_ref_id}/revoke",
          "route_template": "/inference/credential-refs/{credential_ref_id}/revoke",
          "scope": "inference:admin",
          "purpose": "Revoke the reference and gate dependent provider routes.",
          "path_fields": ["credential_ref_id"],
          "request_fields": ["revoke_reason", "disable_provider_routes"],
          "response_fields": ["ok", "credential_ref", "revocation", "routes_gated", "safety_fields"]
        }
      ]
    },
    {
      "group": "provider_runtime",
      "summary": "Provider-agent runtime records for enrollment, pairing, heartbeat, catalog, capacity, and passive health.",
      "endpoints": [
        {
          "method": "POST",
          "path": "/inference/providers/enroll",
          "route_template": "/inference/providers/enroll",
          "scope": "inference:sell",
          "purpose": "Enroll a provider-agent runtime using credential_ref or credential_ref_id only.",
          "request_fields": ["owner_id", "workspace_id", "provider_name", "provider_api", "base_url", "credential_ref_id", "credential_ref", "supported_units", "contact"],
          "response_fields": ["ok", "provider", "runtime_status", "pairing_required", "safety_fields"]
        },
        {
          "method": "POST",
          "path": "/inference/providers/{provider_id}/pairing-token",
          "route_template": "/inference/providers/{provider_id}/pairing-token",
          "scope": "inference:sell",
          "purpose": "Create short-lived pairing token metadata for a provider runtime.",
          "path_fields": ["provider_id"],
          "request_fields": ["requested_by", "ttl_seconds", "purpose"],
          "response_fields": ["ok", "provider_id", "pairing_token", "expires_at", "token_value_redacted", "safety_fields"]
        },
        {
          "method": "POST",
          "path": "/inference/providers/{provider_id}/heartbeat",
          "route_template": "/inference/providers/{provider_id}/heartbeat",
          "scope": "inference:sell",
          "purpose": "Record provider-agent liveness and runtime metadata.",
          "path_fields": ["provider_id"],
          "request_fields": ["runtime_id", "status", "observed_at", "load", "warnings"],
          "response_fields": ["ok", "provider_id", "last_heartbeat_at", "health_status", "safety_fields"]
        },
        {
          "method": "POST",
          "path": "/inference/providers/{provider_id}/catalog",
          "route_template": "/inference/providers/{provider_id}/catalog",
          "scope": "inference:sell",
          "purpose": "Publish supported models, compatible APIs, and capability metadata.",
          "path_fields": ["provider_id"],
          "request_fields": ["catalog_version", "models"],
          "response_fields": ["ok", "provider_id", "catalog", "accepted_model_count", "safety_fields"]
        },
        {
          "method": "POST",
          "path": "/inference/providers/{provider_id}/capacity",
          "route_template": "/inference/providers/{provider_id}/capacity",
          "scope": "inference:sell",
          "purpose": "Publish available units and ask prices for market depth.",
          "path_fields": ["provider_id"],
          "request_fields": ["capacity_version", "inventory"],
          "response_fields": ["ok", "provider_id", "capacity", "created_orders", "safety_fields"]
        },
        {
          "method": "GET",
          "path": "/inference/providers/{provider_id}/health",
          "route_template": "/inference/providers/{provider_id}/health",
          "scope": "inference:read",
          "purpose": "Return passive health, credential-ref status, and route-gating state.",
          "path_fields": ["provider_id"],
          "response_fields": ["ok", "provider_id", "status", "credential_ref_status", "catalog_status", "capacity_status", "route_gate", "safety_fields"]
        }
      ]
    },
    {
      "group": "market_mechanics",
      "summary": "Dry-run order book, cancellation, depth, and reservations.",
      "endpoints": [
        {
          "method": "POST",
          "path": "/inference/market/orders",
          "route_template": "/inference/market/orders",
          "scope": "inference:buy|inference:sell",
          "purpose": "Create a dry-run bid or ask order.",
          "request_fields": ["side", "buyer_id", "provider_id", "model", "unit_type", "units", "limit_unit_price", "currency", "min_fill_units", "time_in_force", "routing_policy", "idempotency_key"],
          "response_fields": ["ok", "order", "matched_fills", "safety_fields"]
        },
        {
          "method": "POST",
          "path": "/inference/market/orders/{order_id}/cancel",
          "route_template": "/inference/market/orders/{order_id}/cancel",
          "scope": "inference:buy|inference:sell",
          "purpose": "Cancel an active dry-run order.",
          "path_fields": ["order_id"],
          "request_fields": ["cancel_reason", "requested_by"],
          "response_fields": ["ok", "order", "cancelled_at", "safety_fields"]
        },
        {
          "method": "GET",
          "path": "/inference/market/depth",
          "route_template": "/inference/market/depth",
          "scope": "inference:read",
          "purpose": "Return bid/ask depth, spread, recent fills, and active dry-run reservations.",
          "query_fields": ["model", "unit_type", "provider_id", "limit"],
          "response_fields": ["ok", "model", "unit_type", "bids", "asks", "spread", "recent_fills", "reservations", "safety_fields"]
        },
        {
          "method": "POST",
          "path": "/inference/market/reservations",
          "route_template": "/inference/market/reservations",
          "scope": "inference:buy",
          "purpose": "Hold capacity as an expiring dry-run reservation without funds movement.",
          "request_fields": ["buyer_id", "provider_id", "model", "unit_type", "requested_units", "max_unit_price", "hold_seconds", "allow_partial", "idempotency_key"],
          "response_fields": ["ok", "reservation", "held_units", "expires_at", "matched_orders", "safety_fields"]
        }
      ]
    },
    {
      "group": "routing_payment_analytics",
      "summary": "Route policy, disabled payment challenge preview, usage analytics, and export.",
      "endpoints": [
        {
          "method": "POST",
          "path": "/inference/quote",
          "route_template": "/inference/quote",
          "scope": "inference:plan",
          "purpose": "Return compatible dry-run quotes and rejected routes under policy.",
          "request_fields": ["agent_id", "workspace_id", "task_id", "model", "unit_type", "estimated_units", "market_policy"],
          "response_fields": ["ok", "quotes", "rejected_routes", "warnings", "safety_fields"]
        },
        {
          "method": "POST",
          "path": "/inference/route",
          "route_template": "/inference/route",
          "scope": "inference:plan",
          "purpose": "Select the safest eligible route under policy.",
          "request_fields": ["agent_id", "workspace_id", "task_id", "model", "unit_type", "estimated_units", "market_policy"],
          "response_fields": ["ok", "route_decision", "selected_quote", "rejected_routes", "warnings", "safety_fields"]
        },
        {
          "method": "POST",
          "path": "/inference/market/payment-challenge/preview",
          "route_template": "/inference/market/payment-challenge/preview",
          "scope": "inference:buy",
          "purpose": "Return disabled payment challenge audit metadata. Execution stays disabled.",
          "request_fields": ["order_id", "reservation_id", "buyer_id", "provider_id", "estimated_total_cost", "currency", "acknowledge_disabled_execution"],
          "response_fields": ["ok", "payment_challenge_preview", "execution_enabled", "requires_signature", "requires_sensitive_signing_material", "safety_fields"]
        },
        {
          "method": "GET",
          "path": "/inference/analytics/usage",
          "route_template": "/inference/analytics/usage",
          "scope": "inference:read",
          "purpose": "Query usage and savings analytics.",
          "query_fields": ["agent_id", "provider_id", "model", "workspace_id", "route_id", "task_id", "from", "to", "format"],
          "response_fields": ["ok", "usage_records", "summary", "redaction", "safety_fields"]
        },
        {
          "method": "GET",
          "path": "/inference/analytics/export",
          "route_template": "/inference/analytics/export",
          "scope": "inference:audit",
          "purpose": "Export JSON or NDJSON usage data for agents, dashboards, and auditors.",
          "query_fields": ["format", "agent_id", "workspace_id", "model", "from", "to"],
          "response_fields": ["ok", "export", "format", "schema_version", "records", "redaction", "safety_fields"]
        }
      ]
    },
    {
      "group": "sdk_proxy",
      "summary": "SDK-compatible proxy entrypoints with Flow Memory route metadata.",
      "endpoints": [
        {"method": "GET", "path": "/v1/models", "route_template": "/v1/models", "scope": "inference:proxy", "purpose": "SDK-compatible model list."},
        {"method": "POST", "path": "/v1/chat/completions", "route_template": "/v1/chat/completions", "scope": "inference:proxy", "purpose": "SDK-compatible chat completions."},
        {"method": "POST", "path": "/v1/responses", "route_template": "/v1/responses", "scope": "inference:proxy", "purpose": "SDK-compatible responses."},
        {"method": "POST", "path": "/v1/embeddings", "route_template": "/v1/embeddings", "scope": "inference:proxy", "purpose": "SDK-compatible embeddings."}
      ]
    }
  ],
  "agent_quickstart_bundle": {
    "base_url": "http://127.0.0.1:8765",
    "sdk_base_url": "http://127.0.0.1:8765/v1",
    "default_model": "flow-memory-orchestrator",
    "steps": [
      "GET /inference/market/depth",
      "POST /inference/quote",
      "POST /inference/route",
      "POST /inference/market/orders",
      "POST /inference/market/reservations",
      "POST /v1/chat/completions",
      "POST /inference/market/payment-challenge/preview",
      "GET /inference/analytics/export"
    ],
    "minimal_policy": {
      "allowed_models": ["flow-memory-orchestrator"],
      "max_unit_price": 0.0000008,
      "min_discount_bps": 500,
      "allow_fallback": true,
      "require_healthy_provider": true,
      "dry_run_required": true,
      "raw_credentials_allowed": false,
      "broadcast_enabled": false,
      "sensitive_signing_inputs_allowed": false
    }
  }
}