The three APIs the DataOps server implements

When you register one base URL with the platform, the platform calls three paths under it. In the examples, https://data.example.com/api is the base URL.

The paths must have exactly this shape. In return, the field names in responses can follow your own conventions — the platform accepts several names with the same meaning (see Field aliases below).

Common conventions#

1. Dataset list#

curl -H "Authorization: Bearer $TOKEN" \
  "https://data.example.com/api/datasets?page=1&page_size=50&updated_after=2026-07-01T00:00:00Z"

{
  "items": [
    {
      "id": "ds-inspect-2026w29",
      "name": "Line inspection images 2026-W29",
      "modality": "image",
      "file_count": 412,
      "size_bytes": 1073741824,
      "updated_at": "2026-07-21T09:30:00Z"
    }
  ],
  "page": 1,
  "total": 3
}

• The platform sends page (starting at 1). page_size is added only by the connection test (page=1&page_size=1) and when a caller of the platform API supplies it. The on-screen remote dataset list sends only page.
• If you split the list into pages, always return total. The screen asks for the next page through "Load more" only while it has loaded fewer items than total. Without total it treats the first response as the whole list, so later pages never show. If you do not paginate, ignore page · page_size and return everything.
• When updated_after arrives, return only what changed after that time (recommended). The screen does not send it; it is passed on, in UTC (…Z), only when a script calls GET /api/v1/external-sources/{id}/remote-datasets?updated_after=….
• A sync does not call the list. It uses only the manifest and file paths.

2. Manifest#

curl -H "Authorization: Bearer $TOKEN" \
  "https://data.example.com/api/datasets/ds-inspect-2026w29/manifest"

{
  "dataset_id": "ds-inspect-2026w29",
  "name": "Line inspection images 2026-W29",
  "modality": "image",
  "updated_at": "2026-07-21T09:30:00Z",
  "annotation_format": "coco",
  "classes": [{ "id": 0, "name": "defect_a" }, { "id": 1, "name": "defect_b" }],
  "files": [
    {
      "file_id": "f-0001",
      "filename": "20260721_line3_0001.png",
      "kind": "image",
      "size_bytes": 2493833,
      "sha256": "9f8a1c…",
      "meta": { "line": "line-3", "measured_at": "2026-07-21T09:30:12+09:00" }
    }
  ]
}

If any entry lacks a file_id or filename, the whole manifest cannot be read and that sync fails.

3. File body#

curl -H "Authorization: Bearer $TOKEN" -o 0001.png \
  "https://data.example.com/api/datasets/ds-inspect-2026w29/files/f-0001"

• Stream the file body as is. Any Content-Type works.
• Redirects are followed, so you may return a 302 to a presigned URL instead of the body. The Authorization header is not sent to a different host, so the presigned URL must work without the token.
• Resuming (Range) is not used yet. A failed file is fetched again in full on the next sync.
• Each file can be up to 2 GiB (configurable in the server settings). A larger file is cut off mid-transfer and recorded as a warning.

Error responses#

// 401
{ "error": "invalid_token", "message": "The token has expired." }
// 404
{ "error": "dataset_not_found", "message": "ds-xxxx was not found." }
// 429
{ "error": "rate_limited", "message": "Please try again later." }

The platform does not interpret this body; it shows the start of it to the user. It must contain one sentence that states the cause.

The platform does not retry an error response and does not read Retry-After. If a file call fails, only that file is recorded as a warning and it is fetched again on the next sync. If the manifest call fails, that sync fails.

Field aliases#

You can use any of the names below for response fields. The platform looks for them in order and uses the first non-empty value.

If you really need a name not in this table, ask the platform team to add an alias.

Supported file formats#

The extension cannot tell CSV · TSV · Parquet time series from tables. If the manifest gives a per-file kind of timeseries or tabular, the platform follows it. Otherwise the dataset modality decides (tabular gives tables, anything else time series); in that case report modality as tabular in the list, or choose the modality directly when the dataset is created.

Integration checklist (provider side)#

Before registering with the platform, call the three paths yourself with curl. The commands are the same as "Try it" in the Reference implementation. The platform's Test connection (연결 확인) calls only the list, so check the manifest and file paths here.