API リファレンス

このセクションでは Data Hub の公開 REST エンドポイントをリソース別に示します。各ページにはメソッドとパス、認証、パラメータ、実レスポンス例とフィールド説明、想定エラー、対応するクライアントメソッドがあります。本ページは全エンドポイント共通の規約だけを扱います。

ベース URL

項目	値
ベース URL	`https://api-datahub.octoparse.com`
パス接頭辞	すべてのエンドポイントは `/v1` で始まる
プロトコル	HTTPS。リクエスト/レスポンス本文は JSON

/v1 契約は追加のみです。新しいフィールドやエンドポイントは増え得ますが、公開済みフィールドの名前と意味は変わりません。未知フィールドは無視し、順序に依存しないでください。

認証

認証が必要なエンドポイントは標準の Bearer 認証を使います。Data Hub API キーを Authorization ヘッダーに置きます。

Authorization: Bearer <your API key>

API キーは Octoparse アカウントセンターで作成します。Web ログインや OAuth のアクセストークンも同じ場所に置けます。各エンドポイントページの認証クラス:

クラス	意味
匿名	資格情報不要
任意認証	資格情報なしでも可。付けるとログイン時フィルタや追加コンテンツが使える
API キー必須	資格情報必須
App 作者のみ	資格情報必須、かつその App の発行者のみ。他者は `404`

Data Hub API は Authorization: Bearer のみ受け付けます。URL クエリに資格情報を置けません。上部ナビの Octoparse スクレイパー MCP が使う x-api-key とは別規約です。混ぜないでください。API キーはアカウント資格情報として扱い、リポジトリや公開画面に出さないでください。

レスポンス形式

成功は data、エラーは error に包まれ、同時には出ません。

{ "data": { "...": "..." } }

{
  "error": {
    "code": "unauthorized",
    "category": "forbidden",
    "message": "valid API key or access token required (Authorization: Bearer <credential>)",
    "retryable": false
  }
}

一部エンドポイントは非 JSON（生 Markdown、CSV/JSONL、zip）を返します。該当ページに明記します。

エラー

フィールド	意味
`code`	分岐用の安定 ID（例: `unauthorized`、`app-not-found`）
`category`	`invalid_input` / `not_found` / `forbidden` / `temporary`
`message`	開発者向け英語説明。分岐には使わない
`retryable`	同一リクエストの再試行が有効か
`details`	入力検証失敗時のみ。フィールド単位の `path` と `message`

多くのエンドポイントで共通:

HTTP	`code`	意味
401	`unauthorized`	API キー欠落または無効
404	`*-not-found`	不存在または不可視（意図的に区別しない）
400	`invalid-input`	本文またはパラメータ不正

ページネーション

一覧系は offset / limit を使い、pagination を返します。has_more が true なら offset に count を足して続行します。

時間パラメータ

時間範囲を取るエンドポイントは ISO 8601 を受け付けます。2026-09-01T00:00:00+08:00 のようにオフセット明示を推奨します。Unix 秒は不可です。

App 参照

形式	例	注意
安定 ID	`app_a1b2c3d4e5f6`	改名後も有効。長期統合はこちら
人が読める形式	`carol/reviews-query`	`<namespace>/<app_name>`。改名で壊れる

1 対 1 共有 App は市場検索に出ません。検索の shared-with-me フィルタを使います。

実行ステータス

ステータス	意味	終端
`PENDING`	受理済み、未キュー	いいえ
`QUEUED`	実行待ち	いいえ
`RUNNING`	実行中	いいえ
`SUCCEEDED`	成功	はい
`PARTIALLY_SUCCEEDED`	部分成功。出力済みレコードは利用可	はい
`FAILED`	失敗。データ料金なし	はい
`CANCELLED`	取消。出力済みは保持・課金	はい
`EXPIRED`	タイムアウト	はい

エンドポイントグループ

Data App の発見

検索、詳細、バージョン、README、仕様、翻訳

実行と結果

開始、取得、一覧、取消、レコード、デバッグ痕跡

データセット

結果の永続化と保持フラグ

アカウントと請求

累計支出と期間・次元の集計

シークレット

作者がアプリ用に保存する上流資格情報

公開と運用

Draft → Build → Release、共有、翻訳、契約ツール、分析

はじめに

クイックスタート

リファレンス

DATA HUB API

ベース URL

認証

レスポンス形式

エラー

ページネーション

時間パラメータ

App 参照

実行ステータス

エンドポイントグループ

Data App の発見

実行と結果

データセット

アカウントと請求

シークレット

公開と運用

​ベース URL

​認証

​レスポンス形式

​エラー

​ページネーション

​時間パラメータ

​App 参照

​実行ステータス

​エンドポイントグループ

Data App の発見

実行と結果

データセット

アカウントと請求

シークレット

公開と運用

ベース URL

認証

レスポンス形式

エラー

ページネーション

時間パラメータ

App 参照

実行ステータス

エンドポイントグループ