<span id="检索图纸"></span>

# Search drawings

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

Find the current version by exact drawing number or retrieve relevant drawings using text/images. Hits group by source file with available text/page provenance evidence.

```text
POST https://api.moi.matrixorigin.cn/v5/drawings/search
```

<span id="调用前准备"></span>

## Before you call this API

Set `MOI_ENDPOINT` to the product API prefix `https://api.moi.matrixorigin.cn/v5`. For private deployments, use the corresponding product API URL.

Prepare a personal access token, workspace ID, drawing knowledge base ID, and indexed data in the target environment. X-Workspace-ID selects the workspace; semantic_model.use is required for the knowledge base. Replace example42 and variables with actual same-environment values. Semantic retrieval may call configured models and incur usage. Confirm source data, indexes, and model availability separately.

<span id="请求参数"></span>

## Request parameters

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
curl --request POST "$MOI_ENDPOINT/drawings/search" \
  --header "X-API-Key: $AI_STUDIO_API_KEY" --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data '{"knowledge_base_id":42,"drawing_number":"AB-001"}'
```

Semantic retrieval using text:

```bash
curl --request POST "$MOI_ENDPOINT/drawings/search" \
  --header "X-API-Key: $AI_STUDIO_API_KEY" --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data '{"knowledge_base_id":42,"query":"带法兰的接头","top_k":8}'
```

Retrieve using a local image; do not manually set the multipart boundary:

```bash
curl --request POST "$MOI_ENDPOINT/drawings/search" \
  --header "X-API-Key: $AI_STUDIO_API_KEY" --header "X-Workspace-ID: $WORKSPACE_ID" \
  --form "knowledge_base_id=42" --form "top_k=8" --form "file=@$QUERY_IMAGE"
```

:::::
:::::{tab-item} Parameters

[Request fields and three retrieval modes](search-inputs.md) distinguishes JSON/multipart, drawing-number priority, and top_k limits.
:::::
::::::
:::::::

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "drawings": [
      {
        "source_file_id": "source-example",
        "drawing_id": "cad-example",
        "score": 0.9,
        "best_hit": {
          "source_file_id": "source-example",
          "score": 0.9,
          "text_id": "text-example",
          "text_kind": "dimension",
          "canonical_text": "标注：0±0.1",
          "recognition_status": "partial",
          "status_reasons": [
            "candidate_only"
          ],
          "coordinate_space": "source_page_px",
          "source_refs": [
            {
              "artifact": "report-example",
              "json_pointer": "/metadata/ocr_text",
              "method": "crop_ocr"
            }
          ],
          "structured_refs": [
            "dimension-example"
          ],
          "dimension_candidate": {
            "text_id": "text-example",
            "nominal": 0,
            "value_min": -0.1,
            "value_max": 0.1,
            "unit": "mm",
            "raw_text": "0±0.1",
            "authority": "candidate"
          }
        },
        "supporting_hits": [],
        "external_source_uri": null,
        "visual_manifest_file_id": null,
        "provenance_status": "legacy_unmigrated",
        "gaps": [
          "drawing_provenance_unmigrated"
        ],
        "pages": null
      }
    ],
    "count": 1,
    "match_mode": "semantic",
    "diagnostics": {
      "total_ms": 1,
      "plan_ms": 0,
      "merge_ms": 0,
      "aggregate_ms": 0,
      "channels": [
        "text_l1"
      ],
      "candidate_hit_count": 1,
      "unique_drawing_count": 1,
      "result_count": 1,
      "identifier_route_used": false,
      "identifier_hit_count": 0,
      "identifier_filename_hit_count": 0,
      "identifier_l1_hit_count": 0,
      "vector_hit_count": 1
    }
  }
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| code | string | OK on success. |
| msg | string | OK on success. |
| data.drawings | object (array of objects) | Hits grouped by source file. See [Response fields](drawing-results.md) for complete objects, evidence, and diagnostics. |
| data.count | integer | Drawings returned by this request, not a library-wide or paginated total. |
| data.match_mode | string | exact or semantic; may be omitted on some empty-result paths. |
| data.diagnostics | object | Diagnostics for this retrieval, not proof of recall coverage or permissions. |

:::::
::::::
:::::::

<span id="错误响应"></span>

## Error response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "ErrDrawingCurrentUnavailable",
  "msg": "Service unavailable"
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| code | string | Examples: ErrParamInvalid, ErrDrawingCurrentUnavailable, ErrServiceSlotUnavailable, ErrForbidden. |
| msg | string | Regular localized error message; the example is English. Billing admission rejection uses numeric code/message with reason and other diagnostics. See [Related APIs](index.md). |

:::::
::::::
:::::::
