> ## Documentation Index
> Fetch the complete documentation index at: https://www.octoparse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API リファレンス

> Data Hub REST API のベース URL、認証、レスポンス形式、ページネーション、エラー、時間パラメータ、App 参照とエンドポイント索引。

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

## ベース URL

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

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

## 認証

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

```http theme={null}
Authorization: Bearer <your API key>
```

API キーは <a href="https://www.octoparse.com/console/open-platform/api-keys" target="_blank" rel="noopener noreferrer">Octoparse アカウントセンター</a>で作成します。Web ログインや OAuth のアクセストークンも同じ場所に置けます。

各エンドポイントページの認証クラス:

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

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

## レスポンス形式

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

```json theme={null}
{ "data": { "...": "..." } }
```

```json theme={null}
{
  "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`             | タイムアウト            | はい  |

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

<CardGroup cols={2}>
  <Card title="Data App の発見" href="/docs/jp/datahub/api/reference/discovery/search-data-apps">検索、詳細、バージョン、README、仕様、翻訳</Card>
  <Card title="実行と結果" href="/docs/jp/datahub/api/reference/runs/start-run">開始、取得、一覧、取消、レコード、デバッグ痕跡</Card>
  <Card title="データセット" href="/docs/jp/datahub/api/reference/datasets/list-datasets">結果の永続化と保持フラグ</Card>
  <Card title="アカウントと請求" href="/docs/jp/datahub/api/reference/account/get-account">累計支出と期間・次元の集計</Card>
  <Card title="シークレット" href="/docs/jp/datahub/api/reference/secrets/list-secrets">作者がアプリ用に保存する上流資格情報</Card>
  <Card title="公開と運用" href="/docs/jp/datahub/api/reference/publishing/validate-manifest">Draft → Build → Release、共有、翻訳、契約ツール、分析</Card>
</CardGroup>