# Responses API

> The Responses API is the primary inference interface for Rowe 1.0. Use it for synchronous spatial reasoning requests that return typed model outputs and request-level usage metadata.

Source: https://fourechelon.com/docs/responses-api · Machine-readable: https://fourechelon.com/openapi.json · Index: https://fourechelon.com/llms.txt

## Request

| Field | Type | Description |
| --- | --- | --- |
| model | string | Model id. Use rowe-1.0. |
| input.task_type | string | fit, stability, placement, embed, understand, reconstruct, predict, act, or optimize. |
| input.cad_scene | object | Native CAD scene with B-rep solids, drawing entities, dimensions, constraints, and optional feature_tree. Preferred for STEP, IGES, DXF, PDF, SVG, and draw.io workflows. |
| input.previous_cad_scene | object | Optional previous native CAD scene for compare and temporal tasks. |
| input.point_cloud_scene | object | Current 3D scene with one or more point cloud groups. |
| input.previous_point_cloud_scene | object | Optional previous scene for temporal prediction. |
| input.image / input.images | object | Optional raster frames, depth maps, or multi-view visual context. |
| input.sensor_readings | object | Optional IMU, GPS, BLE, WiFi, altimeter, or device state readings. |
| input.goal | object | Optional target state for action, routing, placement, or optimization tasks. |
| input.object_id | string | Primary object id used by fit, stability, placement, and tracking tasks. |
| input.secondary_id | string | Target or container object id for fit and placement tasks. |
| input.detail | string | Use compact to reduce structured prediction detail for small or latency-sensitive requests. |

```bash
curl https://fourechelon.com/api/v1/responses \
  -H "Authorization: Bearer $FOUR_ECHELON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rowe-1.0",
    "input": {
      "task_type": "fit",
      "object_id": "case",
      "secondary_id": "shelf",
      "point_cloud_scene": {
        "point_clouds": [
          {
            "object_id": "case",
            "kind": "box",
            "points": [
              { "x": 0, "y": 0, "z": 0 },
              { "x": 1, "y": 0, "z": 0 },
              { "x": 0, "y": 1, "z": 1 }
            ]
          }
        ]
      }
    }
  }'
```

## Response

| Field | Type | Description |
| --- | --- | --- |
| id | string | Unique response id. |
| object | string | The object type. Usually response. |
| model | string | The model that generated the response. |
| output | array | Typed spatial outputs for the requested task. When the request carried a cad_scene, understand, describe, and compare add output[].data.cad_scene: named objects with absolute bounds and parents, connectors with direction, spatial relations, title block, and callout counts; compare adds output[].data.cad_scene_diff (added, removed, moved, re-parented, rewired, dimensions changed). |
| usage | object | Input spatial tokens, output spatial tokens, projected input cost, projected output cost, and total estimated cost. |
| request_id | string | Request id for support and debugging. |

```json
{
  "id": "resp_4e1f45c7ebd1",
  "object": "response",
  "model": "rowe-1.0",
  "output": [
    {
      "type": "fit_result",
      "data": {
        "feasible": false,
        "confidence": 0.2862,
        "explanation": "Transformer multimodal model predicts fit feasibility=false.",
        "reasoning_scene": {
          "schema_version": "reasoning_scene.v2",
          "scene_id": "four-cad-analysis",
          "task_type": "fit",
          "objects": [],
          "relations": [],
          "overlays": [],
          "measurements": [],
          "reasoning_steps": [],
          "suggested_changes": [],
          "issue_regions": [],
          "fit_results": [],
          "comparison_results": [],
          "geometry_changes": [],
          "text_explanation": "The highlighted geometry shows why the fit check failed."
        }
      }
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 29,
    "estimated_input_cost_usd": 0.000042,
    "estimated_output_cost_usd": 0.000116,
    "estimated_cost_usd": 0.000158
  },
  "request_id": "req_..."
}
```