Preview a REST API source sample

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

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

Before you call this API

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

Request body

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"}}'

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.

Successful response

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "status_code": 200,
    "records": [],
    "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.

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.

Last updated on