REST API

プラン: Premium、Ultimate
提供形態: GitLab.com
ステータス: ベータ版

この機能の利用可否は機能フラグによって制御されています。詳細については、履歴を参照してください。この機能はテスト目的で利用可能ですが、本番環境での使用には対応していません。

Orbit REST APIを使用すると、スクリプト、CIパイプライン、またはカスタムツールからナレッジグラフに直接クエリを実行できます。

認証

すべてのエンドポイントには、read_apiスコープを持つGitLabパーソナルアクセストークンが必要です。Bearerトークンとして渡してください。

--header "Authorization: Bearer <your_token>"

結果は、トークンオーナーがGitLabでアクセスできるエンティティにスコープされます。

課金

APIコールはサブスクリプションのGitLabクレジットを消費します。POST /api/v4/orbit/queryへの各コールはクレジットを消費します。その他のエンドポイントは消費対象外です。

エンドポイント

メソッド	エンドポイント	説明
`POST`	`/api/v4/orbit/query`	グラフクエリを実行する
`GET`	`/api/v4/orbit/schema`	現在のスキーマをフェッチする
`GET`	`/api/v4/orbit/status`	インデックス作成のステータスを確認する
`GET`	`/api/v4/orbit/tools`	利用可能なMCPツール定義を一覧表示する

クエリエンドポイント

OrbitクエリDSLを使用してグラフクエリを実行します。

リクエストボディには以下が含まれます。

query: Orbitクエリオブジェクト。
format: オプションのレスポンス形式。構造化されたJSONにはrawを、AIエージェント向けに最適化されたコンパクトなテキストにはllmを使用します。デフォルト: llm。

例:

curl --request POST \
  --header "Authorization: Bearer <your_token>" \
  --header "Content-Type: application/json" \
  --data '{"query": <query_json>, "format": "raw"}' \
  "https://gitlab.com/api/v4/orbit/query"

完全なDSLについては、クエリ言語リファレンスを参照してください。

リクエスト例

パイプラインの失敗が最も多いプロジェクトを検索するリクエストの例:

リクエストボディをrequest.jsonに記述します。

{
  "query": {
    "query_type": "aggregation",
    "nodes": [
      {"id": "pl", "entity": "Pipeline", "filters": {"status": "failed"}},
      {"id": "p", "entity": "Project", "columns": ["name", "full_path"]}
    ],
    "relationships": [
      {"type": "IN_PROJECT", "from": "pl", "to": "p"}
    ],
    "group_by": [{"kind": "node", "node": "p"}],
    "aggregations": [
      {
        "function": "count",
        "target": "pl",
        "alias": "failed_pipelines"
      }
    ],
    "aggregation_sort": {"column": "failed_pipelines", "direction": "DESC"},
    "limit": 10
  },
  "format": "raw"
}

curl --request POST \
  --header "Authorization: Bearer <your_token>" \
  --header "Content-Type: application/json" \
  --data @request.json \
  "https://gitlab.com/api/v4/orbit/query"

レスポンス例:

{
  "result": {
    "format_version": "2.0.0",
    "query_type": "aggregation",
    "nodes": [],
    "edges": [],
    "group_columns": [
      {
        "name": "p",
        "kind": "node",
        "node": "p",
        "entity": "Project"
      }
    ],
    "columns": [
      {
        "name": "failed_pipelines",
        "function": "count",
        "target": "pl"
      }
    ],
    "rows": [
      {
        "p": {
          "type": "Project",
          "id": "1",
          "properties": {
            "name": "payments-api",
            "full_path": "my-org/payments-api"
          }
        },
        "failed_pipelines": 47
      }
    ]
  },
  "query_type": "aggregation",
  "raw_query_strings": null,
  "row_count": 1
}

スキーマエンドポイント

現在のオントロジー（すべてのノードタイプ、そのプロパティと型、およびすべてのリレーションシップタイプ）を返します。

curl --header "Authorization: Bearer <your_token>" \
  "https://gitlab.com/api/v4/orbit/schema"

クエリを作成する前に、利用可能なエンティティタイプとプロパティを確認するために使用してください。

ステータスエンドポイント

Orbitが有効になっているグループのインデックス作成ステータスを返します。

curl --header "Authorization: Bearer <your_token>" \
  "https://gitlab.com/api/v4/orbit/status"

レスポンス例:

{
  "status": "indexed",
  "domains": {
    "sdlc": {"indexed": true, "last_updated": "2026-05-05T14:22:00Z"},
    "code": {"indexed": true, "last_updated": "2026-05-05T14:18:00Z"}
  },
  "projects": {
    "total": 847,
    "indexed": 847
  }
}

ツールエンドポイント

MCPクライアントと互換性のある形式で、query_graphとget_graph_schemaのMCPツール定義を返します。

curl --header "Authorization: Bearer <your_token>" \
  "https://gitlab.com/api/v4/orbit/tools"