<span id="预览-rest-api-来源样例"></span>

# Preview a REST API source sample

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

Use a saved connector's connection details to read records and field samples from the source's first page.

```text
POST https://api.moi.matrixorigin.cn/v5/connectors/{id}/rest-api/preview
```

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

## Before you call this API

Prepare a personal access token for the target workspace and the connector operation permissions. See [common information](objects.md) for draft files, source endpoints, and environment boundaries.

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

## Request body

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

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/connectors/$CONNECTOR_ID/rest-api/preview" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary '{"path":"/records","method":"GET","records_path":"$.data","pagination":{"type":"none"}}'
```

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

The request body has a 1 MiB read limit. Do not submit or overwrite saved base_url/auth. The preview uses saved connection details and this request's endpoint configuration. It retrieves at most 20 records from the first page and limits the serialized result to 512 KiB; exceeding it returns a preview-too-large error. This does not validate the entire source, later pages, or import completion. OPTIONS may check the source but does not guarantee business records.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Required in path | Valid REST API import connector ID in the current workspace. |
| `path` | string | Yes | Source endpoint path starting with /, not a full URL. |
| `method` | string | Yes | GET, OPTIONS, or a POST explicitly declared read-only. |
| `read_only_post` | boolean | Required for POST | Set true for POST. This caller declaration does not turn a source write operation into a read-only operation. |
| `params` | object[] | No | Endpoint query parameters, each containing name/value strings. |
| `headers` | object[] | No | Endpoint request headers, each containing name/value strings; must not conflict with connection authentication or reserved headers. |
| `json` | string | No | Valid JSON text, not a directly nested JSON object. Cannot be combined with data. |
| `data` | object[] | No | Form fields, each containing name/value strings. Cannot be combined with json. |
| `records_path` | string | No | Record extraction path, such as $.data. Set according to the actual source response. |
| `schema_path` | string | Required as a pair | Supply with schema_format; must be nonempty. |
| `schema_format` | string | Required as a pair | columns or json_schema. |
| `pagination` | object | Yes | none, page, offset, cursor, or next_url. See common information. |
| `cursor_param` | string | Required as a pair | Incremental starting parameter name, supplied with initial_cursor; not an ordinary pagination cursor. |
| `initial_cursor` | string | Required as a pair | Starting incremental value for this preview. |

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

<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": {
    "status_code": 200,
    "records": [],
    "fields": []
  }
}
```

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

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | Response information. |
| `data` | object | Result of this action. |
| `data.status_code` | integer | Source HTTP response status, separate from the HTTP status of this MOI request. |
| `data.records` | object[] | Limited first-page record sample. Empty does not mean the source never contains data. |
| `data.fields` | object[] | Declared or sample-inferred fields. |
| `data.fields[].name` | string | Field name. |
| `data.fields[].path` | string | Source field path. |
| `data.fields[].source_type` | string | Source type description. |
| `data.fields[].suggested_target_type` | string | Suggested target type; does not mean a target table was created. |
| `data.fields[].nullable` | boolean | Whether the field is nullable. |
| `data.fields[].required` | boolean | Whether the field must be present. |

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

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

## Error responses

Handle configuration errors separately from source execution failures. MOI may wrap source errors as HTTP 502 `ErrConnectorRESTRead`. A source HTTP status in the message is not this request's status. See [errors and environments](objects.md#errors-and-environments).
