<span id="读取任务内知识证据"></span>

# Read knowledge evidence within a task

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

Read knowledge evidence within a task.

```text
POST https://api.moi.matrixorigin.cn/v5/semantic-models/runtime/read-evidence
```

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

## Before you call this API

Use only the injected service address, technical credentials, workspace, and short-lived authorization in the current task environment. Preserve the original authorization header. An ordinary PAT neither replaces task identity nor establishes authorization. Examples use jq. See [common information](../../ai-studio/agents/message-connections/objects.md) for variables, objects, and states.

<span id="请求体"></span>

## Request body

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

```bash
curl -X POST "${MOI_ENDPOINT%/}/semantic-models/runtime/read-evidence" \
  -H "X-API-Key: $MOI_API_KEY" \
  -H "X-Workspace-ID: $MOI_WORKSPACE_ID" \
  -H "X-MOI-Runtime-Authorization: $MOI_RUNTIME_AUTHORIZATION" \
  -H 'Content-Type: application/json' \
  --data-binary "$(jq -n --arg REQUEST_ID "$REQUEST_ID" --arg ARTIFACT_ID "$ARTIFACT_ID" --arg CHUNK_ID "$CHUNK_ID" --arg FILE_ID "$FILE_ID" --argjson SEMANTIC_MODEL_ID "$SEMANTIC_MODEL_ID" '
{
  "request_id": $REQUEST_ID,
  "artifact_id": $ARTIFACT_ID,
  "chunk_id": $CHUNK_ID,
  "file_id": $FILE_ID,
  "semantic_model_id": $SEMANTIC_MODEL_ID,
  "cursor": 0,
  "limit_chars": 4000
}
')"
```

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

Read using original identifiers. Single-segment mode uses has_more/next_cursor. Evidence lists use object cursors and complete=true for completion. part_index uses part_count to choose the next part. Do not mix modes. Local digests require complete original content; modified or preview-only content is insufficient.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | Yes | Unique operation ID, 1–256 bytes, without leading/trailing whitespace or an audit: prefix. Retain it when replaying identical input. |
| `artifact_id` | string | Conditionally required | Artifact ID previously returned in the same task; not supplied at the top level for batch local-read mode. |
| `chunk_id` | string | No | Select the original segment in single-segment mode. |
| `file_id` | string | No | Original file ID, to resolve duplicate names when needed. |
| `semantic_model_id` | integer | No | Original model ID, to resolve duplicate names across models when needed. |
| `cursor` | integer or object | No | Character offset for single segments; item_index/content_offset object for evidence lists. |
| `limit_chars` | integer | No | Character window. Single-segment omission/0 uses 2000; valid range 1–8000. |
| `part_index` | integer | No | Artifact part index, nonnegative; only with artifact_id. |
| `local_content_sha256` | string | No | Digest supplied after reading the original passage completely locally; not combined with pagination. |
| `local_reads` | object (array of objects) | No | Atomically register complete local reads of multiple segments; not combined with top-level single-segment/pagination fields. |

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

<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": {
    "call_id": "request_example",
    "output": {
      "artifact_id": "artifact_example",
      "semantic_model_id": 7,
      "chunk_id": "chunk_example",
      "file_id": "file_example",
      "content": "示例原文",
      "content_chars": 4,
      "cursor": 0,
      "next_cursor": 4,
      "has_more": false
    }
  }
}
```

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

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | Response description. |
| `data.call_id` | string | Corresponding original request_id. |
| `data.failed` | boolean | true indicates business failure; false may be omitted. |
| `data.output` | object | Current operation result. |
| `data.artifacts` | object (array of objects) | Original artifacts and evidence from the same task. |
| `data.metadata` | object | Operation metadata, when present. |
| `data.output.artifact_id` | string | Raw value returned by the current operation; retain according to common objects. |
| `data.output.semantic_model_id` | integer | Raw value returned by the current operation; retain according to common objects. |
| `data.output.chunk_id` | string | Raw value returned by the current operation; retain according to common objects. |
| `data.output.file_id` | string | Raw value returned by the current operation; retain according to common objects. |
| `data.output.content` | string | Original text in the current window. |
| `data.output.content_chars` | integer | Raw value returned by the current operation; retain according to common objects. |
| `data.output.cursor` | integer | Raw value returned by the current operation; retain according to common objects. |
| `data.output.next_cursor` | integer | Continue according to the current read mode. Markdown ends at 0. |
| `data.output.has_more` | boolean | Whether a single evidence segment has more characters. |

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

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

## Error responses

Handle HTTP status, business results, and error fields. See [errors and environments](../../ai-studio/agents/message-connections/objects.md#错误与环境). On source/version conflicts, read current state rather than automatically replacing identities, resources, or request IDs and retrying.
